Loading ToonBoom animations in XNA

Catalin Zima — Sat, 29 Aug 2009 10:33:10 +0000

Last time, I talked about my experience with drawing and animating 2D images with ToonBoom. In the end of that post, I said that one way to load ToonBoom animations in XNA was to export the animation as a sequence of images, and then load these images and animate them in XNA. So today we will look at a quick way to to just that.

The exporting part is easy enough: just user File->Export Movie in ToonBoom, and then select Image Sequence as the Export Format. The result will be a collection of images, depending on the framerate you choose. The result from my cat animation can be seen in this archive.

The next step is assembling all the images in a single image, usually called a sprite-sheet. Of course, you could also simply load all the images as they are in several Texture2D variables, but working with sprite-sheets yields better performance. For the creation of the sprite-sheet, there are several options.

The first one is to open an image processing application, load all small images, and assemble them in a single image manually. You can imagine this is time consuming, and only worthy if you plan on doing this operation for a very small number of sprites.

The second option, which I used for this sample, is to write a small program that takes the images as input, and generates the sprite-sheet as you want it. My version of this was quickly hacked in a few minutes, so you can see from the source code (get it here) that it makes several assumptions:

all input images are the same size, and are rectangular
the output sprite will contain all input sprites arranged on a single row
the input files are all named similarly (cat1.png, cat2.png, …, cat14.png)

While definitely not an elegant solution, it did it’s job, and I was quickly able to obtain the following image (click for larger size):

The third option, which is the recommended one for a larger project, is to use a more complex program for creating sprite-sheets. You can either create one yourself, based on certain file formats you want to use internally, or around certain restrictions you want to impose on your engine; or you can use an existing one, such as Ziggyware’s Sprite Sheet Creator. Note that if you go for this option, you’ll have to follow certain conventions in your runtime code, imposed by your program used for creating the sprite-sheets.

That being said, we now have a sprite sheet with all the frames of the walking cat animation, and are ready to load this in XNA.

After creating a new XNA project, I read through Nick’s article about Sprite Sheet Animations, and created the following class to hold all information needed for animations. For a detailed explanation, go ahead and read Nick’s article.

class Animation
{
    Rectangle[] frames;
    float frameLength = 1f / 5f;
    float timer = 0f;
    int currentFrame = 0;
  
    /// 
    /// Gets of sets the FPS of the animation
    /// 
    public int FramesPerSecond
    {
        get { return (int)(1f / frameLength); }
        set { frameLength = 1f / (float)value; }
    }
  
    /// 
    /// Gets the Rectangle containing the current frame of animation
    /// 
    public Rectangle CurrentFrame
    {
        get { return frames[currentFrame]; }
    }
  
    /// 
    /// Creates an animation object
    /// 
    ///  the total width of the input image
    ///  the height of the input image
    ///  the number of frames in the sprite-sheet
    ///  the X origin of the sprite-sheet
    ///  the Y origin of the sprite-sheet
    public Animation(int width, int height, int numFrames, int xOffset, int yOffset)
    {
        frames = new Rectangle[numFrames];
        int frameWidth = width / numFrames;
        for (int i = 0; i < numFrames; i++)
        {
            frames[i] = new Rectangle(xOffset + (frameWidth * i), yOffset,
                                      frameWidth, height);
        }
    }
  
    /// 
    /// update the animation
    /// 
    ///  seconds since the last frame
    public void Update(float elapsed)
    {
        timer += elapsed;
  
        if (timer >= frameLength)
        {
            timer = 0f;
            currentFrame = (currentFrame + 1) % frames.Length;
        }
    }
  
    /// 
    /// resets the animation
    /// 
    public void Reset()
    {
        currentFrame = 0;
        timer = 0f;
    }
  
}

Next, I created a class for the cat, holding a few members we need for the animation.

class Cat
{
    Texture2D texture;              //sprite-sheet containing the cat animation
    Animation walkingAnimation;     //animation object used for animating
    Vector2 velocity;               //movement direction
    float movementSpeed;            //movement speed
    Vector2 origin;                 //origin of the image
    bool isMirrored = false;        //draw the image mirrored
  
    public Vector2 Position { get; set; }   //position on the screen

Nothing really special here… Maybe except the isMirrored variable. We use this because our image for the cat shows it facing left. So when we want it to move towards the right, rather than creating a separate sprite with the cat facing right, we mirror the existing sprite. Of course, you can’t always use this trick (or a right-handed character suddenly becomes left-handed), but there are many cases when this trick is enough.

The constructor is straightforward, with some hard-coded values tweaked until I was satisfied with how things looked.

public Cat(Texture2D texture, int frameCount, Vector2 origin)
{
    this.texture = texture;
    //create a new animation object
    walkingAnimation = new Animation(texture.Width, texture.Height, frameCount, 0, 0);
  
    //tweak the FramesPerSecond and movementSpeed values until you're satisfied with how things move
    walkingAnimation.FramesPerSecond = 14 * 3;
    movementSpeed = 256;
  
    //reset position
    Position = Vector2.Zero;
  
    this.origin = origin;
}

For movement, input from both keyboard and gamepad is analyzed, and the velocity’s value is updated.

public void HandleInput()
    {
        KeyboardState keyState = Keyboard.GetState();
        GamePadState gamepadState = GamePad.GetState(PlayerIndex.One);
  
        velocity = Vector2.Zero;
  
        if (gamepadState.IsConnected)
        {
            velocity = gamepadState.ThumbSticks.Left;
            velocity.Y *= -1;
        }
  
        if (keyState.IsKeyDown(Keys.Left))
            velocity.X = -1.0f;
        if (keyState.IsKeyDown(Keys.Right))
            velocity.X = 1.0f;
        if (keyState.IsKeyDown(Keys.Up))
            velocity.Y = -1.0f;
        if (keyState.IsKeyDown(Keys.Down))
            velocity.Y = 1.0f;
    }

In the Update function, we first look which way the cat is facing, and update the value of isMirrored. Then, if the cat is moving, we update the animation and position on the screen.

public void Update(GameTime gameTime)
    {
  
        //mirror the cat if we are moving towards the right
        if (velocity.X > 0.1f)
            isMirrored = true;
        if (velocity.X < -0.1f)
            isMirrored = false;
  
        //normalize velocity vector
        if (velocity.Length() > 1.0f)
            velocity.Normalize();
  
        //get elapsed seconds
        float elapsed = (float)gameTime.ElapsedGameTime.TotalSeconds;
  
        //only animate if we are moving
        float speed = velocity.Length();
        if (speed > 0.0f)
            walkingAnimation.Update(elapsed * speed);
  
        //update position
        Position += velocity * elapsed * movementSpeed;
    }

Finally, the Draw function takes as a parameter the active spriteBatch, and draws the current animation frame using it. Here we can see how to mirror the sprite using SpriteEffects.FlipHorizontally.

public void Draw(SpriteBatch spriteBatch)
    {
        SpriteEffects spriteEffect = SpriteEffects.None;
  
        //mirror the image if necessary
        if (isMirrored)
            spriteEffect = SpriteEffects.FlipHorizontally;
  
        spriteBatch.Draw(texture, Position, walkingAnimation.CurrentFrame,
                        Color.White, 0.0f, origin, 1.0f, spriteEffect, 1.0f);
    }

With this class created, using it in our Game class is trivial. Simply load the texture in LoadContent() and create a Cat object, update it’s input and internal state in Update() and draw it in Draw().

public class Game1 : Microsoft.Xna.Framework.Game
{
    GraphicsDeviceManager graphics;
    SpriteBatch spriteBatch;
    Cat cat;
  
    public Game1()
    {
        graphics = new GraphicsDeviceManager(this);
        Content.RootDirectory = "Content";
    }
  
    protected override void LoadContent()
    {
        spriteBatch = new SpriteBatch(GraphicsDevice);
  
        //load cat texture
        Texture2D catTexture = Content.Load("catWalk");
  
        //create cat object
        cat = new Cat(catTexture,14,new Vector2(64,128));
  
        //place it in the center of the screen
        cat.Position = new Vector2(400, 300);
    }
  
    protected override void Update(GameTime gameTime)
    {
        // Allows the game to exit
        if (GamePad.GetState(PlayerIndex.One).Buttons.Back == ButtonState.Pressed)
            this.Exit();
  
        //update cat's input
        cat.HandleInput();
        //update cat's state
        cat.Update(gameTime);
  
        base.Update(gameTime);
    }
  
    protected override void Draw(GameTime gameTime)
    {
        GraphicsDevice.Clear(Color.CornflowerBlue);
  
        spriteBatch.Begin();
        //draw cat
        cat.Draw(spriteBatch);
        spriteBatch.End();
  
        base.Draw(gameTime);
    }
}

If you run the game now, you’ll be able to move the cat around the screen with the keyboard or the mouse. As you can see, getting an animation from ToonBoom into an XNA game is not difficult at all.

I hope you enjoyed this short post, and if you did, you can download the source for this sample here: ToonBoomAnimationSample.zip

Catalin's XNA Blog » Kitty

Loading ToonBoom animations in XNA

Coming soon…