event.phase

Type String
Event sprite
Revision Release 2022.3683
Keywords sprite, phase

Overview

A string indicating the phase which the SpriteObject animation is currently in.

In a theoretical example of a sprite animation of 4 frames, here are the possible phase-frame scenarios:

-- Loop twice
"began"   1
"next"    2
"next"    3
"next"    4
"loop"    1
"next"    2
"next"    3
"ended"   4

-- Loop indefinitely, no bounce (like above but no "ended" phase occurs)
"began"   1
"next"    2
"next"    3
"next"    4
"loop"    1
"next"    2
"next"    3
"next"    4
--etc.

-- Loop indefinitely, with bounce
"began"   1
"next"    2
"next"    3
"bounce"  4
"next"    3
"next"    2
"loop"    1
"next"    2
"next"    3
--etc.

-- Loop twice, with bounce
"began"   1
"next"    2
"next"    3
"bounce"  4
"next"    3
"next"    2
"loop"    1
"next"    2
"next"    3
"bounce"  4
"next"    3
"next"    2
"ended"   1

Example

-- Assumes "imageSheet" is already created via "graphics.newImageSheet()"

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 )

local function spriteListener( event )
    print( event.name, event.target, event.phase, event.target.sequence )
end

-- Add sprite listener
character:addEventListener( "sprite", spriteListener )