It's sprite mania!

Image sheets are 2D animations that compile multiple frames into a single texture image. This is an efficient way to save on texture memory. It is beneficial for mobile devices and minimizes the loading time.

Image sheet API

The graphics.newImageSheet function creates a new image sheet. Refer to the following code:

graphics.newImageSheet( filename, [baseDir, ] options )

For example, the number of frames in the image sheet is assumed to be floor(imageWidth/frameWidth) * floor(imageHeight/frameHeight). The first frame is placed at the top-left position and reads left to right and follows the next row, if applicable. The following image sheet has five frames that are 128 x 128 pixels each. The image sheet image is 384 pixels x 256 pixels altogether. If it were to be integrated in Corona, a sample method would be displayed like this:

local options =
{
  width = 128,
  height = 128,
  numFrames = 5,
  sheetContentWidth=384, 
  sheetContentHeight=256
}
local sheet = graphics.newImageSheet( "mySheet.png", options )

The display.newSprite(imageSheet, sequenceData) function creates a new sprite from an image sheet. A sprite defines the collection of frames that belong to the same character or other moving asset, which may then be subdivided into different animation sequences for playback. The sequenceData parameter is an array of animation sequences that you set up. Sequences can be shared between multiple sprite objects. The following are some examples:

• Single sequence (consecutive frames):

  local sequenceData =
  {
    name="run", start=1, count=5, time=200, loopCount=0
  }
  
  local myCharacter = display.newSprite(imageSheet, sequenceData)

• Single sequence (non-consecutive frames):

  local sequenceData =
  {
    name="jump", 
    frames= { 6, 7, 8 }, 
    time=200,
    loopCount=0
  }
  
  local myCharacter = display.newSprite(imageSheet, sequenceData)

• Multiple sequences (both consecutive and non-consecutive frames):

  local sequenceData =
  {
    { name="run", start=1, count=5, time=200 },
    {name="jump", frames= { 6, 7, 8 }, time=200, loopCount=0 }
  }
  
  local myCharacter = display.newSprite(imageSheet, sequenceData)

• object:pause(): This pauses the current animation. The frame remains on the current displayed frame.
• object:play(): This plays an animation sequence, starting at the current frame.
• object:setFrame(): This sets the frame in the currently loaded sequence.
• object:setSequence(): This loads an animation sequence by name.