Michalis Kamburelis edited this page Dec 11, 2015 · 4 revisions

Castle Game Engine http://castle-engine.sourceforge.net/ has an advanced support for Spine http://esotericsoftware.com/ 2D animations.


Spine is a great software to design 2D animations for games, using modern techniques (bones, skins, meshes etc.). Animations done this way are lightweight: their loading and rendering is very efficient, even on mobile devices like Android or iOS. But they are also very flexible:

  • they look smooth regardless of the playback speed,
  • you can reuse the same animations by changing skins,
  • you can change attachments during animation,
  • and more (see Spine website for exhaustive list :).

You can use view3dscene http://castle-engine.sourceforge.net/view3dscene.php to open Spine animations, so try it now!

  1. Our engine examples contain sample animations in castle_game_engine/examples/2d_dragon_spine_android_game/data/ . Try also example Spine projects (downloaded along with Spine installation). Of course, if you already use Spine, try it on your existing Spine projects too!
  2. Just open a project exported from Spine (as a JSON file) using view3dscene File->Open.
  3. To run an animation, use Animations->Named Animations menu item, and choose one of the animations. You may want to use first the Force Looping menu item, otherwise Spine animations don't loop by default.

Dragon Spine - Castle Game Engine demo

How to use Spine animations in your own games

Example 2d_dragon_spine_android_game

First of all, see our simple 2D game example in castle_game_engine/examples/2d_dragon_spine_android_game/game.pas . The source code is really simple, we just load the game and let the character move. The main code is inside code/game.pas file (view 2d_dragon_spine_android_game/game.pas directly here ). The game can be compiled for standalone (Linux, Windows, Mac OS X, many others) as well as to Android.

Overview of Spine and 2D usage in the engine

See our engine tutorial for an overview how to use the engine and what is a scene manager.

To easily use Spine animations in a 2D world, use a 2D scene manager (T2DSceneManager) and scene instance (T2DScene) from Castle2DSceneManager unit. They adjust our normal scene manager (TCastleSceneManager) and scene loader (TCastleScene), to make them perfect for 2D worlds. The adjustments are really minor (look inside the Castle2DSceneManager unit source if you're curions), so you may as well use diretly the TCastleSceneManager and TCastleScene, and go wild mixing 2D and 3D inside a single game. This is possible because our implementation of Spine converts the Spine project under the hood into an X3D node graph. This means that Spine animation is a full 3D model, and can use stuff like interpolators for animation.

This also means that you can use all existing X3D rendering/processing tools to extend the Spine animation (for example, you can use sensors, texture settings, screen effects, you can cast shadows!, you can use shaders etc.).

Note that you could also create an X3D file with your 2D world, where you insert multiple Spine animations with X3D Inline node. The example 2d_dragon_spine_android_game shows this too. This allows to combine multiple 2D and 3D models already at data level.

To play a Spine animation, use TCastleScene.PlayAnimation. Use TCastleScene.Animations to list named animations. These are called "named animations" in our engine, and you can actually use them with any 3D model (that appopriately names it's animations, more precisely: X3D TimeSensor nodes), not only Spine.

Underneath, we also support multiple Spine skins. You can choose a skin at loading, by loading a filename like my_animation.json#my_skin_name instead of my_animation.json. You need to know the available skin names beforehand (you see them in Spine, and in our log console, for example you can run view3dscene with --debug-log command-line option to see them).

Creating Spine models

Basically, just create Spine models/animations as usual, and export them to JSON. Often it is comfortable to test your animations first in view3dscene before trying them out in your game.


We fully support all Spine texture atlas options. It is advised (although not required) to create an atlas when you export to JSON, as rendering with atlas will be more efficient. The default atlas creation options are Ok (in particular Bleed should be ON, as it by default; it is necessary to avoid visible seams later).

Spine features support

Notable features supported

  • Of course, full display of skeleton with attachments, and full playback of normal bone animations.
  • Animation of slot timeline attachment, this allows to change the attachment during animation, e.g. to make something appear/disappear or for frame-by-frame animations.
  • Animation of slot color and transparency.
  • Animating slot draw order (draw order timeline).
  • Bezier curves for animating parameters.
  • Skin support, by default we choose the first (non-default) skin, but you can use URL like my_animation.json#my_skin_name to open with any skin.
  • Full support for atlas format generated during Spine import. This includes handling multiple atlas pages, stripping whitespace, rotating... so you can pack your atlases really tight.
  • You can also work without the atlas (we expect images then to be inside images/.png).
  • Support for "mesh" attachment.
  • Partial support for "skinnedmesh" attachment. The skinnedmesh in setup pose is affected by bones correctly, and during animation it moves as a whole (is affected by parent bone transformation). Missing is the ability to recalculate vertexes affected by bones during animation (that is, to deform skinnedmesh during animation).

Missing (contributions are welcome!)

Some more exotic Spine animation features are not implemented (yet!). If you would like to see support for them please submit a feature request or ask on Castle Game Engine forum or submit a patch yourself :). Many of the below features are really simple to implement (it is only a matter of adding simple reading and conversion to X3DLoadInternalSpine unit, see engine sources).

  • Attachment type "regionsequence" (should be easy, but needs test models; in principle, this should be exactly how you can use things like "xxx@counter(4).png" in X3D MovieTexture with our engine, see http://castle-engine.sourceforge.net/x3d_extensions.php#section_ext_movie_from_image_sequence ).
  • Attachment type "boundingbox" (easy to do, convert to X3D TransformSensor; will need special code to actually use it for something).
  • Events and Event Timeline (easy to do; note that events don't do anything by themself, they just allow animator to "name" some events on the timeline; we would convert them to some sensor that can be watched (using X3D ROUTE) by user code).
  • Animating vertexes of meshes using FFD. Should be easy, this is just CoordinateInterpolator in X3D.
  • Animating vertexes of skinned meshes to deform them by the bones. Should be easy, as it is already started --- skinned meshes are correctly calculated in setup pose. It remains to calculate them for all frames of related bones, and for frames where FFD changes, and use CoordinateInterpolator.
  • IK (Inverse Kinematics). Difficulty unknown, this is a new Spine feature.
  • Cross-fading between animations. This is not really a "Spine feeature", but it's something possible thanks to Spine providing us with bone information. As part of this, we should investigate / propose a general method to add cross-fading animations to X3D. This may be quite simple actually, like: "some output events send a value with given weight, and at the end of frame, all fields set this way (with weights) are recalculated as a sum of all values received (in this frame) with appropriate weights".

 Spine 2D animations rendered using Castle Game Engine (view3dscene) New Spine features in Castle Game Engine, including slot timeline attachments