display.newSprite()

Type Function
Library display.*
Return value SpriteObject
Revision Release 2022.3683
Keywords sprite, animation
See also Sprite Animation (guide)
Image Sheets (guide)

Overview

Creates a sprite object. Sprites allow for animated sequences of frames that reside on image sheets. Please see the Sprite Animation and Image Sheets guides for more information.

The local origin is at the center of the sprite and the anchor point is initialized to this local origin.

By default, sprites use frames that reside on a single image sheet. This corresponds to the image sheet you pass to the display.newSprite() constructor.

For each sequence, you can specify a different image sheet instead of using the default image sheet. You do this by using the optional sheet parameter in a sequenceData table. For details, see Sequence Data below.

Syntax

display.newSprite( [parent,] imageSheet, sequenceData )
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.

Sequence Data

This is a table which holds data for one of more sequences. Sequences may be shared between multiple sprite objects.

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.

Examples

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 )