Getting Started with Spine Skeletal Animations with Cocos2D-x v3

Firstly let me mention the current Spine master and example doesn’t compile in XCode, seems there are a couple of missing files and a path not set in the example project. Here is a complete guide to download and install:

  • Download the Spine runtime (click the “Download Zip” button on the right, extract the files):
  • Download Cocos2d-x v3.2 if you don’t have it already from here:   – extract the files.
  • Rename your “spine-runtime-master” folder to “Spine”
  • Rename your “cocos2d-x-3.2” folder to “Cocos2d-x”
  • Make sure your Spine and Cocos2d-x folders are in the same path, e.g:

Screen Shot 2014-09-02 at 16.59.23

  • Open the Spine Cocos2d-x V3 sample, see:

Screen Shot 2014-09-02 at 16.59.50

Go into the project setting, click the “Spine iOS” settings, find the “Header Search Paths” and set the search paths to the following:


Screen Shot 2014-09-02 at 18.43.06

Do the same for the “Spine Mac” Header Search Paths:


Screen Shot 2014-09-02 at 18.43.21

  • Compile – you will get errors!! Seems the Spine people missed out a couple of files by accident. In the project navigator open up “spine-c/src/spine”, right click on of the .c files in there and select “show in Finder”. You need to add the file (drag in) “IkConstraint.c” and “IkConstraintData.c“. Add them to both the Spine iOS and Spine Mac projects. See the image below for reference.


  • Compile and run!
Running on an iPad
Running on an iPad
Running in a Max OSX window
Running in a Max OSX window

Make Your Own Spine Animation

Next thing you’ll be wanting to do is download the Spine editor and have a play, maybe create your own animation or edit one of the samples.

Get Spine from There is a free trial version, but you can’t export your models with that. For now try the free version to get used to the interface and see that you like it. It is a bit confusing, the best tutorial I’ve seen are Esoteric’s own tutorials (links below). First some hints and tips from me (thing it took me a while to figure out):

Hints and Tips

  1. You have to have “bones” in your model to animate, even to just move a sprite left or right. I wanted to start by just have a base sprite with a child that moved in and out, you can’t even do this unless you first create a bone. It is the bones that you move/rotate to animate.
  2. The documentation is very vague, but have a browse of it anyway, it isn’t very long!
  3. Keyframes are the tool for saying “this is the start position of my bone”, the next keyframe is to say “this is the next position”. What happens in-between is the animation, Spline moves the “bone” (and the sprites connected to it) to the new position smoothly animated. If you’ve used keyframes in other software like Final Cut Pro video editing you will understand this already.
  4. There is a Photoshop script that comes in the Spine folder for exporting all layers of your sprite to individual files, it names the files the same as your PS layers (so name your layers) and creates a JSON file for Spline which is the positions. A coupe of hints on this though:
    1. It’s a little buggy, if it doesn’t create the files then it had a problem. For instance I had a problem with PSD’s that had hidden layers or folders which were hidden, the script just stopped.
    2. Name your layers!
    3. If after your first export, you then use Photoshops Generator to link your layers to the PNG’s. Any changes you make in Photoshop to your sprite will automatically be exported to the PNG’s! No need to use the script a second time.

OK, now go watch the 2 tutorial videos here, try following the tutorial whilst trying to animate your own sprite:

What Version To Buy

The Essentials version is currently $69+tax. You’ll notice there is a piggy bank breaking $289 pro version with extra features for meshes and Inverse Kinetics but I recommend ignoring that for now. If you decide later you need those features you can upgrade for the price difference. I suspect the meshes and IK features will only make your models slower when running too….. I’ve no idea if that is the case, just a nice thought to stop me wanting to spend the extra $200!