animation.setPosition()

Type Function
Return value none
Revision Release 2024.3703
Keywords animation, tween, timeline, interpolation, setPosition
See also Animation — Tweens and Timelines (guide)
Tween
Timeline

Overview

The animation.setPosition() method will move/set the playback position, depending on the passed parameter:

Important

Calls to this method on specific child tweens within a Timeline are ignored. Timeline tweens are controlled/owned by the parent timeline, so you should set the position of the timeline itself via this method or object:setPosition().

Syntax

animation.setPosition( position )
animation.setPosition( tweenObject, position )
animation.setPosition( displayObject, position )
animation.setPosition( tagName, position )
animation.setPosition( timelineObject, position )
position (required)

Number or String. The position (time or marker) to move/set the playback to, as follows:

  • For either normal tweens or timelines, this can be a number indicating the time to move the playback to, in milliseconds.
  • For timelines specifically, this can be a string name of a time marker associated with the timeline.
tweenObject (optional)

Tween. The specific Tween upon which to move/set the position.

displayObject (optional)

DisplayObject. The display object upon which to move/set all tween positions. If the specified position is outside the time range of any tween, that tween will be set to either its initial or final state.

tagName (optional)

String. The tag name; all tweens/timelines with this tag will be affected.

timelineObject (optional)

Timeline. The specific Timeline upon which to move/set the position.

Examples

All Tweens/Timelines
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=4000 } )
local tween2 = animation.to( object2, { y=400 }, { time=2000 } )

-- Set the position of all tweens to 1 second in
animation.setPosition( 1000 )
Specific Tween
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=4000 } )
local tween2 = animation.to( object2, { y=400 }, { time=2000 } )

-- Set the position of a specific tween
animation.setPosition( tween1, 1000 )
Display Object Tweens
local object1 = display.newRect( 50, 50, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=4000 } )
local tween2 = animation.to( object1, { rotation=90 }, { time=2000, delay=2000 } )

-- Set the position of all tweens on the object
animation.setPosition( object1, 3000 )
Tagged Tweens
local object1 = display.newRect( 50, 50, 100, 100 )
local object2 = display.newRect( 50, 150, 100, 100 )

local tween1 = animation.to( object1, { y=300 }, { time=4000, tag="tweenTag" } )
local tween2 = animation.to( object2, { y=400 }, { time=2000, tag="tweenTag" } )

-- Set the position of all tweens with the tag "tweenTag"
animation.setPosition( "tweenTag", 1000 )
Timeline Time Position
local object1 = display.newRect( 50, 50, 100, 100 )

-- Create a timeline object
local timelineParams = {
    tweens = {
        { startTime=0, tween={ object1, { x=400 }, { time=4000, iterations=5 } } },
        { startTime=1000, tween={ object1, { y=400 }, { time=4000, easing=easing.outQuad } } }
    }
}
local newTimeline = animation.newTimeline( timelineParams )

-- Set the timeline playing
newTimeline:resume()

-- Sometime later, set the timeline position to a specific time
animation.setPosition( newTimeline, 2000 )
Timeline Marker Position
local object1 = display.newRect( 50, 50, 100, 100 )

-- Create a timeline object
local timelineParams = {
    tweens = {
        { startTime=0, tween={ object1, { x=400 }, { time=4000, iterations=5 } } },
        { startTime=1000, tween={ object1, { y=400 }, { time=4000, easing=easing.outQuad } } }
    },
    markers = {
        { name="marker_2000", time=2000 }
    }
}
local newTimeline = animation.newTimeline( timelineParams )

-- Set the timeline playing
newTimeline:resume()

-- Sometime later, set the timeline position to a specific time marker
animation.setPosition( newTimeline, "marker_2000" )