Phaser tutorial: Phaser and Spriter skeletal animation

 

Follow @SBC_Games


Previous Phaser tutorials:
Phaser tutorial: DronShooter - simple game in Typescript - Part 3
Phaser tutorial: DronShooter - simple game in Typescript - Part 2
Phaser tutorial: adding 9-patch image support to Phaser
Phaser tutorial: DronShooter - simple game in Typescript - Part 1
Phaser tutorial: custom easing functions for tweening and easing functions with parameters
Phaser tutorial: sprites and custom properties for atlas frames
Phaser tutorial: manage different screen sizes
Phaser tutorial: How to wrap bitmap text

 Recently I was looking for some way how to play skeletal / bone animated characters in Phaser. Unfortunately, there is not too much choices if you just want to try some tool in end-to-end way (from creating animation in tool to playing it in Phaser game).

 Finally, I managed to do it and it is what this article is about. So, read on...

Tools overview

 First I was looking for available tools. I found four which interested me and which I decided to examine deeper:

• Creature - looks very impressive. From Phaser 2.4.0 it is even supported in engine. But, it costs $99 for Basic and $170 for Pro version. In Trial version you cannot save or export your project. It can be good for artist to try the tool, but I am coder and, as already mentioned, my attempt was to try end-to-end implementation. Beside this, it looks that WebGL rendering mode is needed,
• DragonBones - this tool attracted me with it price - it is free. But it looks you need Flash Pro to use it. DragonBones is supported by Adobe. So, buy Adobe Flash Pro to get DragonBones for free :-) Beside this, I did not find any documentation on tool's export files,
• Spine - this tool has documentation on export format, but it does not let you to save and export in trial version. Essential version costs $89 and Professional $289. Hey, I just want to try to make simple animation, export it and implement it in Phaser. I will not blindly buy any tool that does not let me do this - what if its export is horrible mess and making the player will turn into nightmare?,
• Spriter - this tool made by BrashMonkey has also free and Pro version for $59. But, finally tool, that let me try it, export my animation into .xml or .json. Has some documentation on format. Beside this, its use is simple even for programmer and there is also series of video tutorials, that will guide you through program functions. It also shows, what is only in Pro version.

 From above list I selected Spriter. And if in future I wanted to go Pro with some of the tools, I would definitely do so with Spriter, as I now know it little and I invested time into making runtime for Phaser.

Runtimes

 Despite some other tools, Spriter does not come with runtimes. It is up to you to find some already existing one or to write your own. Spriter has forum, where peoples using it and coder implementing runtimes meets. There you can get links to various runtime implementations. From those I found these two attracted me most:

• spriter-scon-js by Dean Giberson. It is reading .scon files, which is .json export from Sprites. The implementation is minimal, but reading it helps you to find what is in export and what are relations between its data structures. Also its length encourages you to write your own!,
• spriter by Trixt0r (Heinrich Reich). This one is more massive supporting Java2D, libGDX and others. I regret that I did not find it earlier. I found it with half of my implementation finished, when I was searching internet for solving reverted y axis issue. At least, I used its test character animation instead of my crappy programmer animation I was using before.

Runtime for Phaser

 Before I will go further here is result: Spriter bone animation running in Phaser (press A to switch to next animation):

 Runtime is written in Typescript and significant part of it is just structure of all objects needed for animation and filling these structures when loading animation data. Currently, this is first version of implementation and only tweening between two positions is linear (will add curves later), but I am happy with the result! Also some features, that are available only in Spriter Pro are not implemented (character maps, sounds, events, ...).

 Second part of source is the player, that takes loaded data and tweens bones and sprites between keyframes and also transforms it from its local spaces into world space.

 Phaser specific is that all visible parts are Phser.Sprite objects and whole character is Phaser.Group object. So, you can further take it and transform (scale, move, rotate) - it is part of scene graph.

Quick export structure overview

 Export begins with information on folders and files. Files are in fact files with individual sprite parts. As I am using atlas I use file names as frame names. Folders can help you to organize your assets, but with atlas I am not using them.

 Next part is Entity. Entity is your character and one file can contain multiple entities. Entity has one or more animations. Entity is that grey guy and animations are short sequences you can either loop or play only once.

 Core of each animation is main timeline - bottom third on editor picture. Whenever you change some part (either bone or sprite) it creates keyframe on main timeline. These keyframes reference to particular timelines for individual bones or sprites. Keyframes are those small vertical rectangles on picture. It keeps information on time, position, rotation, scale, spin ... and file and folder for sprites.

 Of course, during implementation, you will encounter lot of issues. My biggest problem was correct handling of y axis. In Spriter 0,0 point is in top left corner, but when rotating, 90 degrees points up. In export coordinates are exported in "OpenGL" way with 0,0 in bottom left corner, and 90 degrees points up (and after long debugging I also found, that sprite y pivots were reverted during export). In Phaser 0,0 is in top left corner again, but 90 degrees points down. It was necessary to flip all angles along horizontal axis and also correctly handle spins. Spins say in which direction bone or sprite should rotate to its target position.

 Detailed information on structure can be found here and also examining other implementations can fill holes where documentation is not actual or missing.

Conclusion and download

 I am really happy that I managed to make it work. I hope it will help great Phaser community. If you are interested, you can get whole project (MS Visual Studio 2015) here: SpriterExample.zip

 Most of the project is the Spriter player and the rest are some small help classes necessary to run the example.