Type Function Return value Tween Revision Release 2024.3703 Keywords animation, tween, timeline, interpolation, to See also Animation — Tweens and Timelines (guide) animation.from() Tween Timeline
This function animates (interpolates) properties of an object using an optional easing algorithm. It returns a Tween reference corresponding to the interpolation of the object target
.
animation.to( target, properties, params )
DisplayObject or Userdata. The display object, RectPath point, Paint fill, or fill.effect to tween.
Table. A table that specifies the properties of the object that will be interpolated. These include the following options:
x1
, y1
, x2
, y2
, x3
, y3
, x4
, and y4
. See here for more information.r
, g
, b
, and a
).fill
table of a ShapeObject.Table. A table which specifies control parameters for the tween — see the next section for details.
The params
table includes parameters which control aspects of the tween.
Number. Specifies the duration of the tween in milliseconds. Default is 500
.
Number. Adjusts the relative speed scale for the tween. 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.
Number. Specifies the delay, in milliseconds, before the tween begins. Default is 0
.
Number. Specifies the number of times the tween will repeat. By default, the iteration value is 1
(no repeat). To make a tween repeat indefinitely, specify 0
or -1
for this parameter.
Boolean. Specifies whether alternate iterations of the tween are reflected (played back in reverse). Default is false
.
String. Specifies the tween tag. The animation library can pause, resume, cancel, set the position, or set the speed scale of tweens sharing the same tag.
String. An optional identification string to assign to the tween. This can be retrieved as obj.id
from any of the tween event listener functions (see below).
Boolean. Specifies whether non-control parameters are interpreted as final ending values or as changes in value. The default is false
.
Number. Specifies the amount of constantRateProperty
parameter to indicate which object state governs the interpolation. Together, these two parameters can be used to interpolate multiple objects at a constant rate, even if they don't share the same initial/final position, rotation, alpha, or scale. Note that if you supply this parameter, the time
parameter is ignored, since
String. Indicates which object state governs a "position"
, "rotation"
, "alpha"
, or "scale"
. This parameter must be specified if you supply the constantRate
parameter.
Listener. Listener function to be called before the tween begins. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called after the tween completes. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called when the tween is paused. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called when the tween is resumed. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called when the tween is cancelled. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called when the tween completes an iteration in a repeat cycle. This function will receive a reference to the associated Tween as its sole argument.
Listener. Listener function to be called when the tween has its playback position changed manually via animation.setPosition() or object:setPosition().
local square = display.newRect( 0, 0, 100, 100 ) local w, h = display.contentWidth, display.contentHeight local function tweenListener( obj ) print( "Tween completed; ID: " .. obj.id ) end -- Move square to bottom right corner animation.to( square, { x=(w-50), y=(h-50) }, { time=1500, id="tween1", onComplete=tweenListener } )
local square1 = display.newRect( 50, 50, 100, 100 ) square1:setFillColor( 1, 0, 0 ) local square2 = display.newRect( 50, 150, 100, 100 ) square2:setFillColor( 0, 1, 0 ) local square3 = display.newRect( 50, 250, 100, 100 ) square3:setFillColor( 0, 0, 1 ) local w, h = display.contentWidth, display.contentHeight local cr = 50 -- Set a constant rate for movement (pixels per second) -- Move each square at a constant rate to its final position animation.to( square1, { x=(w-50) }, { constantRate=cr, constantRateProperty="position" } ) animation.to( square2, { x=(w-150) }, { constantRate=cr, constantRateProperty="position" } ) animation.to( square3, { x=(w-100) }, { constantRate=cr, constantRateProperty="position" } )
local square = display.newRect( 0, 0, 100, 100 ) -- Tween the path corner points of the square -- Notice that the target being tweened is "square.path", not "square" animation.to( square.path, { x1=10, y1=10, x2=20, y2=-20, x3=-10, y3=-10, x4=-40, y4=40 }, { time=1500 } )
local logo = display.newImageRect( "logo.png", 100, 100 ) -- Apply a hue filter effect to the image logo.fill.effect = "filter.hue" -- Tween the hue filter effect's "angle" property -- Notice that the target being tweened is "logo.fill.effect", not "logo" animation.to( logo.fill.effect, { angle=100 }, { time=1500 } )
local square = display.newRect( 0, 0, 100, 100 ) -- Tween specific RGB+A color channels of the square -- Notice that the target being tweened is "square.fill", not "square" animation.to( square.fill, { r=0, g=0.2, b=0.6, a=0.8 }, { time=1500 } )