Animation Guide

Introduction

Torque 2D features two different ways to animate sprites. There is the traditional frame-based way and there is also support for 2D skeletal animation.

Frame-based Animation

Example

Using a spritesheet to create an animation is a fairly simple process. Several examples are provided in the included Sandbox toys. Let's go over the needed steps:

1. Create an ImageAsset.

Having a look at our wizard spritesheet, we can see that there are quite a few cells to define.

Luckily, we can use implicit cell definitions since all cells are the same size and lined up in a grid. The asset TAML file (in XML format) looks like this:

<ImageAsset
    AssetName="TD_Wizard_CompSprite"
    imageFile="TD_Wizard_Comp.png"
    cellCountX="8"
    cellCountY="8"
    cellWidth="64"
    cellHeight="64"
	 />

2. Create an AnimationAsset.

Once we have an ImageAsset, we can then create an AnimationAsset.

<AnimationAsset
    AssetName="TD_Wizard_WalkNorth"
    Image="@asset=MyModule:TD_Wizard_CompSprite"
    AnimationFrames="32 33 34 35 40 41 42 43 48 49 50 51 56 57 58 59"
    AnimationTime="1.0667"
    AnimationCycle="true"
     />

As you can guess from the name, this is the animation for the wizard walking north, or in the +Y direction on screen. Each AnimationAsset can only define one specific animation - separate AnimationAsset files are needed for other walking directions or other animations for attacking, death, etc.

3. Assign the Animation to a Sprite.

In the Scene, create a Sprite and assign it your animation as follows:

%object = new Sprite();
%object.Animation = "MyModule:TD_Wizard_WalkNorth";

Changing animation states based on input or in-game events is something that you will have to script yourself. See the TorqueScript class reference for Sprites to see the available methods you can use to configure and control your animations.

Named Frames

The default way to define animation frames is via a numerical index of ImageAsset cells that start at 0 and increase to the max cell number of that image. Introduced in T2D 3.0 is the ability to name cells and frames with a unique name.

Skeletal Animation

Another feature added to T2D 3.0 is the ability to animate sprites by creating an underlying skeleton and manipulating that. Currently, T2D supports the export format generated by the animation program Spine.

Example

The goal of this guide is not to show you how to use Spine - please visit the Spine website for more information and help on how to use that program. Here, we will show how to take the exported Spine files and make them available for use within the engine.

1. Copy your Spine files into your module's asset folder.

There are 3 files needed, the PNG image you used, the atlas file for the image (similar to T2D's ImageAsset), and the JSON file that contains bone, skin, and animation information.

2. Create a SkeletonAsset file.

The SkeletonAsset acts as a pointer for the engine so it knows which Spine files to reference and load. There are only a couple manditory fields that need to be configured: AssetName, AtlasFile and SkeletonFile. It is recommended to save the asset file in the same folder as the Spine files you just copied into your module.

<SkeletonAsset
    AssetName="goblins"
    AtlasFile="goblins.atlas"
    SkeletonFile="goblins.json"/>

3. Using a SkeletonObject in your Scene.

Object instances that use 2D skeletal animation have a separate class defined for them called SkeletonObject. Using TorqueScript, you can add a SkeletonObject to your Scene like this:

%spineObject = new SkeletonObject();

%spineObject.Asset = "MyModule:Goblins";
%spineObject.Skin = "GoblinGirl";
%spineObject.setAnimation("walk", true);
%spineObject.RootBoneScale = "0.025";
%spineObject.RootBoneOffset = "0 -5";

MyScene.add(%spineObject);

A SkeletonObject also inherits all of the properties typical to a SceneObject. For more information on the fields and methods available to SkeletonObjects, see the SkeletonObject Guide and the SceneObject Guide.