About framesets in friGame

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:

• imageURL: The URL of the image (default: the one passed as the imageURL parameter if passed, or the imageURL of the first element of the list)
• numberOfFrame: the total number of frame in the sprite-sheet (for example for a 10x10 sprite with 15 frames your image will be 10x150 or 150x10 -- default: 1)
• type: either friGame.ANIMATION_VERTICAL for vertically stacked frames or friGame.ANIMATION_HORIZONTAL for horizontally layed frames (default)
• offsetx: the offset along the x-axis for the position of the first frame in the image (for use with sprite-sheets)
• offsety: the offset along the y-axis for the position of the first frame in the image (for use with sprite-sheets)

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.