animation.setSpeedScale()

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

Overview

The animation.setSpeedScale() method will set the playback speed scale, 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 speed scale of the timeline itself via this method or object:setSpeedScale().

Note

Changing the speed scale does not affect any delay set for starting the playback. In other words, only the actual playing portion of the affected object(s) will be modified by this call.

Syntax

animation.setSpeedScale( scale )
animation.setSpeedScale( tweenObject, scale )
animation.setSpeedScale( displayObject, scale )
animation.setSpeedScale( tagName, scale )
animation.setSpeedScale( timelineObject, scale )
scale (required)

Number. The relative speed scale. This must be a positive number greater than 0. By default, the speed scale is 1 (normal speed). Values greater than 1 will increase the speed while values lower than 1 will decrease it.

tweenObject (optional)

Tween. The specific Tween upon which to set the speed scale.

displayObject (optional)

DisplayObject. The display object upon which to set the speed scale of all tweens.

tagName (optional)

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

timelineObject (optional)

Timeline. The specific Timeline upon which to set the speed scale.

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 speed scale of all tweens and timelines
animation.setSpeedScale( 2.5 )
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 speed scale of a specific tween
animation.setSpeedScale( tween1, 2.5 )
Display Object Tweens
local object1 = display.newRect( 50, 50, 100, 100 )

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

-- Set the speed scale of all tweens on the object
animation.setSpeedScale( object1, 2.5 )
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 speed scale of all tweens with the tag "tweenTag"
animation.setSpeedScale( "tweenTag", 2.5 )
Timeline
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()

-- Set the speed scale of the timeline
animation.setSpeedScale( newTimeline, 2.5 )