display.newSprite()

parent _^(optional)

GroupObject. An optional display group in which to insert the sprite.

imageSheet _^(required)

ImageSheet. Specifies the default image sheet.

sequenceData _^(required)

Table. A table which holds data for a specific sequence. Or, if you have more than one animation sequence for a single object, sequenceData is then an array of tables that hold data for each sequence. For instance, you might have a character object with several different animation sequences such as "walking", "jumping", and "swimming". Frames in a given sequence may be consecutive (1,2,3,4,...) or non-consecutive (1,3,4,6,9,...) within the image sheet. See Sequence Data below.

name _^(required)

String. The unique sequence name, used to load the sequence when it's time to play it.

start _^(optional)

Number. For consecutive-frame sequences, start represents the starting frame.

count _^(optional)

Number. For consecutive-frame sequences, count represents how many frames from the start that the sequence should end.

frames _^(optional)

Array. For non-consecutive-frame sequences, this is an array that holds the frameIndex in the exact order animation should be played.

sheet _^(optional)

ImageSheet. You can specify a per-sequence image sheet. Typically you would do this if you wanted to use a different image sheet. If none is provided, it defaults to the image sheet you provided to display.newSprite(). A single sprite can also pull frames/sequences from different image sheets — see the Multiple Image Sheets example below.

time _^(optional)

Number. This is the time (in milliseconds) for the entire sequence to animate. If not specified, then the per-frame animation rate will be based on the frame rate of your app.

loopCount _^(optional)

Number. This is a number that represents how many times you want the sequence to loop when it is played. Setting this to 1 will play the sequence once and then stop. The default is 0, which will loop the sequence indefinitely.

loopDirection _^(optional)

String. This can either be "forward" or "bounce", with "forward" being the default. The "bounce" option will play forward then backwards through the sequence of frames.

Single Sequence (Consecutive Frames)

-- Example assumes 'imageSheet' is already created from graphics.newImageSheet()

-- consecutive frames
local sequenceData =
{
    name="walking",
    start=3,
    count=6,
    time=100,
    loopCount = 0,   -- Optional ; default is 0 (loop indefinitely)
    loopDirection = "bounce"    -- Optional ; values include "forward" or "bounce"
}

local character = display.newSprite( imageSheet, sequenceData )

Single Sequence (Non-Consecutive Frames)

-- Example assumes 'imageSheet' is already created using graphics.newImageSheet()

-- non-consecutive frames
local sequenceData =
{
    name="walking",
    frames= { 3, 4, 5, 6, 7, 8 }, -- frame indexes of animation, in image sheet
    time = 240,
    loopCount = 0        -- Optional ; default is 0
}

local character = display.newSprite( imageSheet, sequenceData )

Multiple Sequences

-- Example assumes 'imageSheet' already created using graphics.newImageSheet()

local sequenceData =
{
    { name="walking", start=1, count=3 },
    { name="running", frames={ 3, 4, 5, 6, 7, 8 }, time=120, loopCount=4 },
    { name="jumping", start=9, count=13, time=300 }
}

local character = display.newSprite( imageSheet, sequenceData )

Multiple Image Sheets

-- 1st image sheet
local sheetData1 = { width=64, height=64, numFrames=6, sheetContentWidth=384, sheetContentHeight=64 }
local sheet1 = graphics.newImageSheet( "mySheet1.png", sheetData1 )

-- 2nd image sheet
local sheetData2 = { width=64, height=64, numFrames=6, sheetContentWidth=384, sheetContentHeight=64 }
local sheet2 = graphics.newImageSheet( "mySheet2.png", sheetData2 )

-- In your sequences, add the parameter 'sheet=', referencing which image sheet the sequence should use
local sequenceData = {
                { name="seq1", sheet=sheet1, start=1, count=6, time=220, loopCount=0 },
                { name="seq2", sheet=sheet2, start=1, count=6, time=220, loopCount=0 }
                }

local myAnimation = display.newSprite( sheet1, sequenceData )
myAnimation.x = display.contentWidth/2 ; myAnimation.y = display.contentHeight/2
myAnimation:play()

-- After a short time, swap the sequence to 'seq2' which uses the second image sheet
local function swapSheet()
        myAnimation:setSequence( "seq2" )
        myAnimation:play()
end
timer.performWithDelay( 2000, swapSheet )