What are Sprite Sheets?

Sprite sheets are 2D animations packed as multiple frames into a single texture image. This allows a much more efficient use of texture memory, which is highly limited on mobile devices, and also minimizes loading time.

Corona supports two types of sprite sheets: those whose animation frames are all sized and positioned uniformly, and those whose frames have non-uniform sizes and positions. In the former case, you simply provide Corona with the width and height of each frame in the sprite sheet image file to create a new internal representation of the sprite sheet. The image below (from the JungleScene sample project that ships with Corona SDK) is an example of a sprite sheet with uniformly-sized frames.

In the other case, the positions and sizes of individual frames within the sprite sheet are described by an external data file that can be exported from several sprite sheet generator tools (such as Zwoptex or TexturePacker). Corona lets you easily create an internal sprite sheet object from a sprite sheet image and its accompanying data file. See below for examples of how to work with both types of sprite sheets. The sprite sheet below (from the HorseAnimation sample project) contains frames with non-uniform sizes and positions.

Corona also includes constructors for complex animated characters with multiple sequences, and sequence playback methods that are time-based rather than frame-based, so animation duration will remain consistent on slower devices. These time-based sequences also allow you to individually choose and tweak the frame rate for each sequence, rather than having the animation speed locked to the application’s global frame rate.

There may be more than one instance of each sprite on the stage at the same time, playing at different locations and with different durations. A sprite animation behaves like any other Corona display object -- it may be added to a group or transformed, or even used as a Box2D physics object.

The JungleScene sample project demonstrates using two different sprite sheets (both with uniformly-sized frames), to create animations running at different frame rates. To see an example of sprite sheet source images, view the files “greenman.png” and “runningcat.png” in that project folder.

The HorseAnimation sample project demonstrates how to use create a sprite sheet from a Lua data descriptor file and source image whose frames are non-uniformly sized and positioned in the sheet.

Limitations

If you attempt to use a sprite sheet whose width or height exceeds your device's maximum texture size, no image will be displayed.

To check the maximum texture size, use system.getInfo("maxTextureSize").

Summary

For each animation sequence, the developer specifies the following things:

• Source image (the sprite sheet)
• One of the following:
• The height and width of each frame within the sprite sheet (for sprite sheets with uniformly sized frames)
• A Lua data descriptor file that describes the size, position, and other attributes of each frame (for sprite sheets with non-uniformly sized frames). Typically this would be generated by a sprite sheet packing utility.
• Location of sprite frames -- these may not be contiguous!

When drawing an instance of the sprite animation, the developer specifies:

• Destination in the scene
• Optional transforms such as rotate/scale
• Length of animation (time-based)
• Looping behavior

Sprite API

This line makes the sprite features available under the “sprite” namespace:

require "sprite"

sprite.newSpriteSheet

sprite.newSpriteSheetFromData

These functions create new sprite sheets.

The following code creates a new sprite sheet from image containing uniformly-sized frames, but does not add anything to the display list.

spriteSheet = sprite.newSpriteSheet("image.png", frameWidth, frameHeight)

In this case, the number of frames in the sprite sheet is assumed to be floor(imageWidth/frameWidth) * floor(imageHeight/frameHeight). They are indexed in row major order:

1 2 3
4 5 6
7 8 9

spriteSheet = sprite.newSpriteSheetFromData( "image.png", spriteData )

This second form takes as its second parameter a table that describes the frame sizes and positions in the source sprite sheet image.

The code below is an example of a sprite sheet descriptor file named test.lua. It defines a single function named getSpriteSheetData() that returns a Lua table whose elements describe the size, position, and other properties of each frame in the sprite sheet.

-- test.lua
module (...)
 
function getSpriteSheetData()
 
        local sheet = {
                frames = {
                        { 
                        name = "01.png", 
                        spriteColorRect = { x = 38, y = 38, width = 50, height = 50 }, 
                        textureRect = { x = 2, y = 70, width = 50, height = 50 }, 
                        spriteSourceSize = { width = 128, height = 128 }, 
                        spriteTrimmed = true,
                        textureRotated = false
                        },
 
                        {
                        name = "02.png",
                        spriteColorRect = { x = 38, y = 36, width = 50, height = 52 },  
                        textureRect = { x = 2, y = 242, width = 50, height = 52 },  
                        spriteSourceSize = { width = 128, height = 128 },  
                        spriteTrimmed = true,
                        textureRotated = false
                        },
                }
        }
        return sheet
end 

1
2
3
4
5
6
7

local sprite = require("sprite")
-- In this case, test.lua is exported from Zwoptex
local test = require("test.lua")
-- Method defined by test.lua that returns table data defining the sprites
local spriteData = test.getSpriteSheetData()
-- Load the sprite sheet in test.png using the sprite definitions from spriteData
local spriteSheet = sprite.newSpriteSheetFromData( "test.png", spriteData )

In either case, creating a new sprite sheet object does not actually result in anything being added to the display list. To do that you need to create a sprite (and optionally sprite sets) from your sprite sheet object. These concepts are explained further below.

Tip: You can combine sprite sheet loading into one line of code:

local spriteSheet = sprite.newSpriteSheetFromData( "test.png", test.getSpriteSheetData() )

spriteSet = sprite.newSpriteSet(spriteSheet, startFrame, frameCount)

Creates a new sprite set from a sprite sheet. Since a single sprite sheet may contain images from unrelated game characters, a “sprite set” defines the collection of frames that belong to the same game character, which may then be subdivided into different animation sequences for playback. For example, a fighting game character would probably have different animation sequences for punching and for kicking, but these would be defined within the same sprite set.

startFrame is the index number of the first frame of the sprite, using the index defined in newSpriteSheet() above, and frameCount is the total number of frames in the set.

A sprite set is a Lua table containing keys to one or more animation sequences for a given character. Each sprite set is created with an initial sequence named "default", containing all frames in the set, so you can either use this default sequence immediately or define further animation sequences within the set.

sprite.add( spriteSet, "startFlying", startFrame, frameCount, time, [loopCount])

Adds a sequence named "startFlying" to the sprite set with the specified frames. The sequence has frameCount frames, and will play for time milliseconds. You can control the frame rate of each sequence individually by altering this time parameter.

The optional parameter loopParam controls the looping behavior:

• A value of 1 or greater sets the number of times the animation sequence will loop. When done it will stop on the last frame of the sequence.
• A loopParam of 0 (which is the default) means that the sequence will loop indefinitely.
• A loopParam of -1 means that the sequence will "bounce" back and forth exactly once (1, 2, 3, 2, 1).
• Finally, a loopParam of -2 means that the sequence will bounce back and forth forever. In our 3-frame example, this would play in the following order: 1, 2, 3, 2, 1, 2, 3, 2, 1 (...) and so on.

spriteSheet:dispose()

Disposes of a sprite sheet and releases its texture memory. It also calls removeSelf() on all sprite instances using the sheet, removing them from the stage. All sprites, sequences, and sets that belong to the removed sprite sheet are no longer valid after calling this method, and will be garbage collected when they are no longer referenced by your application's Lua code.

1
2
3
4

local sprite = require("sprite")
local spriteSheet = sprite.newSpriteSheet("test.png")
-- Later dispose of the sprite sheet and all of its associated sprites, sequences and sets.
spriteSheet:dispose()

si = sprite.newSprite( spriteSet )

Create a new instance of a sprite. A sprite is a DisplayObject. Sprites play one animation sequence at a time.

si:prepare([sequence])

Stops any currently playing animation sequence, optionally sets the new current sequence, and also moves to the first frame of that sequence. This also resets the loop counter, if any. However, this does not start playing the current sequence.

si:play()

Play animation sequence, starting at the current frame. Does not reset looping.

si:pause()

Stop animation, but the frame remains on the last displayed frame. Playback can resume later with play().

si:addEventListener("sprite", listener)

Notify listener when the spriteInstance animation has an event.

The event, passed to the listener, has the following fields:

event.sprite The sprite that fired the event; its current properties may also be accessed via the event: e.g., event.sprite.sequence.

event.phase
The phase is one of: