About framesets in friGame

Originally posted on the cownado.com blog.

Framesets are the cool new feature in the latest development version of friGame, and in this blog post we will see what they are and the motivation behind their implementation.

The problem

To start, let's review how animations are implemented in friGame:

First of all you have one big image, called sprite-sheet, that contains all the animation frames, aligned one by one either horizontally or vertically.

Then you use the friGame.resourceManager.addAnimation function like this:

friGame.resourceManager.addAnimation('myAnimation', './myAnimation.png', {
    numberOfFrame: 10,
    rate: 90,
    type: friGame.ANIMATION_VERTICAL,
    once: true
});

This works great as long as you're using a PC, but when we tried to run the latest version of Frank the 'dillo using CocoonJS, an error occurred stating that the image exceeds the maximum texture size.

As CocoonJS maps every image to a texture, there is a hardware limit on the texture size, that can be as low as 2048 pixels, so we must find a way to use sprite-sheets whose width or height does not exceed 2048 pixels, and at the same time we don't want a limit on the frames composing an animation.

Re-thinking animations

Who said that an animation must be contained inside one image file only? A single sprite-sheet can already contain multiple animations, but what if a single animation could be contained inside multiple smaller sized sprite-sheets?

In order to maintain backwards compatibility, the friGame.resourceManager.addAnimation function can still be used as the example above, but a new option has been added: frameset, which is a list of objects with the following properties:

As always, not all the parameters are required, use only those that make sense.

So, now we can safely split the animation into multiple files, and use them as a single animation like this:

friGame.resourceManager.addAnimation('myAnimation', './myAnimation.png', {
    numberOfFrame: 10,
    rate: 90,
    type: friGame.ANIMATION_VERTICAL,
    once: true,
    frameset: [
        {
            imageURL: './otherSpriteSheet.png',
            numberOfFrame: 10,
            type: friGame.ANIMATION_VERTICAL,
        }
    ]
});

The parameters specified in the options parameter will refer to the first sprite-sheet, followed by all the sprite-sheets defined in the frameset parameter.

But wait, there is more

The example that we just saw is kinda ugly, with the first sprite-sheet defined in one place, and the other sprite-sheets defined in a different one, so now you can omit the imageURL parameter, and describe all the sprite-sheets in the frameset like this:

friGame.resourceManager.addAnimation('myAnimation', {
    rate: 90,
    once: true,
    frameset: [
        {
            imageURL: './myAnimation.png',
            numberOfFrame: 10,
            type: friGame.ANIMATION_VERTICAL
        },
        {
            imageURL: './otherSpriteSheet.png',
            numberOfFrame: 10,
            type: friGame.ANIMATION_VERTICAL
        }
    ]
});

And that's it, now your animations are not limited anymore.

Stay tuned, as we have some news concerning Frank the 'dillo.