Using Skeletal Animation With Spine


Using Skeletal Animation With Spine

In this article, we're going to introduce you to a very powerful tool for creating naturalistic sprites using skeletal animation. The idea behind this is that you create a base skeleton and then move the bones to create poses. These poses can then be turned into animation key-frames, and in turn you interpolate the bone positions between each key-frame to create a smooth and very natural looking animation. This animation can then be skinned (ie: given a texture) and drawn to the screen like a sprite.

GameMaker Studio 2 supports this type of animated sprite, as it can import files created using the program Spine, which is a fantastic tool for creating skeletal animations (you can find out more about Spine here). Note that Spine is a very powerful program with lots of possibilities and there is not nearly enough room in one short article to explain how it all works! We will however give a brief overview of some key points that are related to the way that GameMaker Studio 2 implements skeletal animation sprites.

NOTE: Spine has a Trial version available for download here: http://esotericsoftware.com/spine-download


SPINE OVERVIEW

As mentioned in the introduction, Spine works by having you create a skeleton and then pose it to create animations. The skeleton is composed of bones, which can be attached and moved in relation to one another over a set time-frame, and the final animation can be skinned with character graphics for the final animation. This animation can then be exported either as a bitmap sprite strip, or as a Spine JSON file for adding into your game in the GameMaker Studio 2 sprite editor.

The Spine Interface

If you are simply exporting a bitmap sprite, then you can stop reading here, as there really isn't much more to say since the method for creating and using "normal" sprites is well known, however if you export the animation using the Spine JSON format export, it permits you to do far more things with your Spine animation than a simple sprite strip.

Some of the most basic features of skeletal animations are:

  • being able to have a single sprite and create multiple animations for it - for example a walking, running and jumping animation set

  • having multiple skins for your sprite, so that a single skeleton can be skinned differently to create multiple characters (all with the same movements, of course) in a single sprite resource

  • you can give your sprites attachments to change their look further by permitting them to wield different items

All these things (and more!) are available to use in GameMaker Studio 2 too when importing JSON sprites.

NOTE: You can find the full documentation for all Spine features here: Spine Documentation

NOTE: GameMaker Studio 2 requires a specific runtime version of Spine to correctly import and use the skeletal animation sprites that it creates. Please see the YoYo Games helpdesk article on Required SDKs for GameMaker Studio 2 to find out the current runtime required.


THE BASICS

Before getting into GameMaker Studio 2 side of things, it's worth going over a few key concepts when using Spine. The first of these is that you need to name your bones and a few other things, and that these names will be what you use as your "handle" into the animations when working with them in GMS2. We recommend that you try and keep any names memorable, short and consistent.

You will also want to pay attention to where the root is in your animation. The root is where your Spine animation would be anchored within the Spine world space, and when you import your sprite into GameMaker Studio 2, this will be translated as the x/y origin for the sprite resource, and this is not editable for this kind of sprite in the GMS2 sprite editor. Most of your calculations for moving parts of the skeleton will also depend on this root point.

The Root Of The Spine Sprite

When creating your animations, you set a pose and then create a key frame from the pose. After that you would advance the timeline for the animation and create another key frame. After doing this Spine will interpolate the bone data between the key frames to give a smooth animation, which can then be named and saved. You can create multiple animation sets for one sprite, and give each one a separate name which can then be used in GameMaker Studio 2 to set the skeletal animation pose for your imported sprite.

There are also attachment slots available for your Spine sprite, and these are points where you can have your sprite draw a separate image that doesn't have a bone. It will then be moved along with the parent bone, permitting you to give your animation multiple sub-images for attaching within a single sprite. These attachment slots should be named appropriately, as should the images that they use, since these names will be used within GameMaker Studio 2 to change attachments at run-time.

Once you have your Spine sprite ready, you can then export it for use with GameMaker Studio 2. When exporting your sprite, please ensure that you have selected the Texture Atlas: Pack option from the export options, as GameMaker requires the generated -atlas file, and this isn't created without this option being checked.

Exporting A Spine Sprite

IMPORTING A SPINE SPRITE

When you export a skeletal animation sprite from Spine as JSON, you will actually be creating three separate files: the base .json file which contains all the bone data and animations, the .atlas file which has the data about how the textures are packed, and a .png file which contains the texture itself. The important thing to note here is that these files must always be in the same folder and all together for the sprite to be correctly imported into GMS2.

Importing A Spine Sprite Into GMS2

The way to import them into the GameMaker Studio 2 is almost identical to that for adding a normal bitmap image - you need to create a new sprite and then click the Import button, which will bring up the standard OS file selector dialogue, and then make sure that you have selected *.json from the file filter at the bottom, before browsing to where you have saved the Spine files and selecting the one you wish to import.

Once you have imported the animation, you can set the collision properties, but note that you are limited here to simply using precise collisions or bounding box collisions, and that the collision data for a skeletal animation is explicitly taken from the data provided. GameMaker Studio 2 does not generate any collision mask if the data is missing from imported file, meaning you simply won't get working collisions if the masks are not set correctly in Spine. Also note that - unlike bitmap sprites - the imported skeletal animation sprite cannot be modified in the image editor in any way, meaning any changes that need to be made should be done in Spine and then re-imported into your game.

NOTE: Due to the complexity of skeletal animations, the preview image shown in the sprite editor is not intended to accurately represent your animation, but rather give you a simple image that represents the animation for visualising in the room editor.


USING SPINE SPRITES IN GAMEMAKER

Once the sprite has been loaded into GameMaker Studio 2, you can use it as you would any other sprite. You can assign them to an object, or set them to an instance in code, and they will respond to most of the sprite instance variables too - so they can be scaled, rotated, coloured and have alpha values changed - all in-game. They can also be drawn using most of the different sprite_*() functions as you would any other sprite, with the exception of draw_sprite_pos(), and draw_sprite_part() which won't work with this kind of sprite.

Spine Sprites In GM Using Regular Sprite Functions

However, the point of using Spine is to create a skeletal animation sprite with multiple poses and skins, which that is most definitely not like a normal bitmap sprite. Therefor GameMaker Studio 2 has a host specific skeleton_*() functions, as well as an Animation Update Event to deal with these types of sprite. The rest of this article will give a brief overview of the most commonly used functions and what they do, but you can find a full explanation of each one in the manual.


ANIMATIONS

skeleton_animation_get();
skeleton_animation_set(name);

These functions will get the name (a string) of the currently set animation for a Spine sprite, or set the sprite to use the named animation. So, say you have a "run" and a "walk" animation, then you would change between them using these functions when the player presses a key (or whatever).

skeleton_animation_get_ext(track);
skeleton_animation_set_ext(name, track);

These functions are similar to the above ones for animations, but slightly more complex in how they work. Spine permits you to define bone animations for only a part of a skeleton, and you can then create separate animation sets for those parts and have them play together. Each animation is assigned to a track, with track0 always being the base, default animation. In this way you may have - for example - a figure with a "walk" animation assigned to it, and this animation only affects the legs. You could then have various other animations where only the arms, or the head, or the upper torso, etc... are moved and assign one of them to track 1 using these functions. GameMaker Studio 2 would then play both animations together.

skeleton_animation_mix(animfrom, animto, duration);

This little function is possibly one of the most important ones when it comes to the final look of your imported sprite. You can change animations at any time using the above mentioned skeleton_animation_set() function, but on doing so the imageindex will be reset to 0, which may make the transition "jumpy" as it goes from one pose to the other. Now, with bitmap sprites this is expected and may even be desirable, but with skeletal animation sprites it looks odd and buggy. However you can remedy this by using the ```skeletonanimation_mix()``` function which will interpolate the given animation sets so that they flow into each other in a natural way. For example, you can set a mix for your "run" animation into your "jump" animation, then set another mix for the "jump" animation to change into the "run" animation and your sprite will now animate seamlessly between the two sets.


SKINS

skeleton_skin_get();
skeleton_skin_set(skinname);

A single skeletal sprite animation can have one or more skins, and these can be switched using the functions above. This means that you can have multiple characters in your game, and all of them can have a different visual look but using the same base sprite animation. GameMaker Studio 2 permits you to use multiple skins for each single sprite in this way, and you can even use multiple texture pages per sprite (this is covered in detail in the helpdesk article Spine: Using Multiple Texture Pages). Note that when you set up your Spine sprite, you should have a target platform in mind and set the texture page size when exporting your sprites to a size appropriate for that target. For example, if you are targeting mobile devices, you might want to have your Spine texture page set for 1024x1024, but for desktop you may want 2048x2048 or larger.

The Spine Texture Packer

ATTACHMENTS

skeleton_attachment_get();
skeleton_attachment_set(slotname, imagename);
skeleton_attachment_create(imagename, sprite, ind, xo, yo, xs, ys, rot);

As mentioned previously, you can attach images to the skeletal animation sprite and they will behave as if they were part of the bone structure of the animation. These functions are used to set this, with you simply selecting the slot name (as defined in Spine) to hold the attachment and the attachment to assign. However, you also have the ability to use any one of the sprite resources that are included in your game - either as part of the base resources or as an included file - which makes these sprites an even more flexible option for games.


DRAWING

skeleton_collision_draw_set(flag);
draw_skeleton_collision(sprite, animname, image_index, x, y, xscale, yscale, rot, colour);
draw_skeleton(sprite, animname, skinname, image_index, x, y, xscale, yscale, rot, colour, alpha);

While you would normally use the draw_sprite_*() functions to draw the skeletal animation sprite, there are times when you may want to draw extra data or a single sub-image of a single animation (for a pause screen, or a special effect, etc...). That's why these functions have been added, with the first of them simply flagging the collision data for drawing or not. If the flag is set to true then you will see the bounding box and the precise mask drawn over the sprite on the screen (this data is created when you create your sprite in Spine), while the second function permits you to draw the collision data for an individual frame of any animation.

Sprite Collision Mask Using Spine

The final function is a bit different, in that it permits you to draw any frame of any animation with any skin, making it a powerful tool for testing things in-game. Note that although you can use this in-game for drawing a frame of a Spine sprite animation, it has a tremendous overhead due to the fact that GameMaker Studio 2 will have to do multiple calculations to correctly position the bones for the given frame, so it should only really be used as rarely as possible.


CONCLUSION

As you can imagine from the outline given above, skeletal animation is an incredibly powerful tool. It permits naturalistic animations with a minimum of effort, and (thanks to the mix function) these animations can flow into each other to create a very smooth user experience in your games. The skin and attachment functions available in GameMaker Studio 2 also mean that you can simplify the generation of multiple sprites from a single source, and even permit the player to customise them at run-time. Obviously, this is not a system that will be applicable to all games, but if you check out the Spine web site and the demo linked below, you will find that it is surprisingly versatile and well worth the time and effort required in making a sprite and importing it into GameMaker Studio 2.

Spine Basic Features Demo

The above demo was created using Spine and shows some of the functions mentioned above in action.



Written by Mark Alexander

Mark Alexander is the former GameMaker technical writer. He’s moved on to pastures new, but still hangs around as admin on the GameMaker Community forum and makes his own indie games as Nocturne Games.