Skeletal animations in javascript with Spine and MelonJS

When we started our html5 game Peter Acorn we were optimistic but cautious about the level of performance we could get from the platform on mobile. We started off with simple spritesheets which looped through our animations frame by frame and were extremely fast to execute. I will assume you either already have a MelonJS game setup or bootstrap yourself with one of the MelonJS tutorials to get up and running.

This was fast to get setup initially with good performance but there are limitations:

  • Getting smooth transitions between animations is difficult.
  • Using an image editor and scripts to structure and export the spritesheets takes time.
One major limitation which eventually broke the camels back with related to resolution and frame rate. If you want to increase the resolution of the game, then your sprite sheet gets much larger. To compound the issue if you want a smoother or more complex animation then adding extra frames to the sprite sheet exasperates the issue the higher the resolution is. You can offset this by having a square sheet but by now we had already seen Spine and wanted to try it.

We were skeptical about the performance of the javascript runtime especially on mobile but these concerns were not warranted in the end. First we had to find a way to get it integrated into MelonJS. You can find an example of this on Github  and a big thanks to Aaron for adding this support to MelonJS! 

You will want to load integration after both the melon and spine runtimes:

<script type="text/javascript" src="lib/melonjs/melonJS-1.1.0.js"></script>
<script type="text/javascript" src="lib/melonjs-spine/spine.js"></script>
<script type="text/javascript" src="lib/melonjs-spine/melonjs-spine.js"></script>

I have already added my chopped assets to Spine and created a few animations. I noticed that I needed to key all the bones otherwise I would get strange behaviour in-game and the animations would be totally out of whack as a result of bad relative co-ordinate data. So on the first frame of each of your animations select all the bones and make sure their rotation, translation and scale is keyed in. Take care especially on mobile to keep the number of bones, images and frames to a minimum to improve performance.

When exporting lets create an atlas which efficiently puts all the components parts of your character onto a single image. 

Turn off rotation (which packs more efficiently) as the integration does not seem to support it, not a huge loss anyway. You can also adjust the scaling factor but if you choose to use this you will also need to adjust the animationScale parameter in the Spine.Entity settings. It does not map directly to the scale factor you plug into here so some experimentation is needed.

You will get three files as a result of the export. The png contains the images for your character. The atlas is the mapping between the images and the skeleton and the json contains the animation data.

{name: 'peter', type:'json', src:'assets/atlas/peter/skeleton.json'},
{name: 'peter_atlas', type:'binary', src:'assets/atlas/peter/skeleton.atlas'},
{name: 'peter_atlas', type:'image', src:'assets/atlas/peter/skeleton.png'},

The integration allows you to create spine entities which will use skeletal animation instead of a sprite sheet. So you can use this base class for your animated entities.

var player = me.Spine.Entity.extend({
    init: function(x, y, settings) {
        var settings = {
            atlas: 'peter_atlas',
            imagePath: 'peter_atlas',
            spineData: 'peter',
            name: 'PlayerEntity',
            imageScale: 1,
            animationScale: 1
        this._super(me.Spine.Entity, "init", [x, y, settings]);

Still within the init method you can adjust how the integration maps your character into the game.

this.anchorPoint = new me.Vector2d(0, 0);
this.renderOffset = new me.Vector2d(0, 0);

The anchorPoint adjusts where the collision box is mapped related to your characters position and their width and height.

this.body.addShape(new me.Rect(-(this.width * this.anchorPoint.x), -(this.height * this.anchorPoint.y), this.width, this.height));

The renderOffset adjusts where the sprite is rendered in relation to the characters position.

context.translate(x + this.renderOffset.x, y + this.renderOffset.y);

Once these are set you can call this.updateColRectToAnchorPoint() to set the collision box on your character. We can now configure the animations on our character. My character Peter will start off with the running animation with 0 delay and we’ll set loop indefinitely to true. We can also set animation mixing using setMixByName which will tween between the animations when they are changed and makes the transitions appear really smooth. The time the runtime takes to smooth between the animations is configurable and I’ve set them to 100ms. The longer this value is the smoother it can look but you will need to experiment to find the best value for your animations.

this.state.setAnimationByName(0, "running", true);

this.stateData.setMixByName("running", "jumping", 0.1);
this.stateData.setMixByName("jumping", "running", 0.1);

You can switch animations by calling:

this.state.setAnimationByName(0, "jumping", true);

You can also set up a playlist of animations to run through using addAnimationByName. Once each animation is complete it will move onto the next one assuming you have queued one up. You will likely have one animation which will then loop indefinitely until a change in gameplay state forces a change. Using these animation queues you can create even smoother transitions than tweening alone.

this.state.setAnimationByName(0, "start-gliding", false);
this.state.addAnimationByName(0, "gliding", true, 0);

If you are taking advantage of spine slots which allow you to change the images associated with the bones then you will need to call setSlotsToSetupPost when changing animation.


Lastly if you want to get the name of the currently executing animation you can use:

var animation = this.state.tracks[0]

Despite using the runtime we were still able to reach 60 FPS on mobile devices as old as 3 years ago like my Galaxy Nexus which is hugely impressive. We managed this using the CocoonJS container and we are looking forward to talking about our experiences with this in the future.

The Spine software is a pleasure to work with and putting together animations is great fun. The large amount of integrations for many game engines and platforms together with the great performance makes it a fantastic package. Highly recommended!

Here are the animations in action although I do not doubt that an experienced animator would be able to do better:

blog comments powered by Disqus