animation.to()

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

Overview

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.

Syntax

animation.to( target, properties, params )
target (required)

DisplayObject or Userdata. The display object, RectPath point, Paint fill, or fill.effect to tween.

properties (required)

Table. A table that specifies the properties of the object that will be interpolated. These include the following options:

params (required)

Table. A table which specifies control parameters for the tween — see the next section for details.

Parameter Reference

The params table includes parameters which control aspects of the tween.

time (optional)

Number. Specifies the duration of the tween in milliseconds. Default is 500.

speedScale (optional)

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.

easing (optional)

Function. Specifies the easing algorithm. Default is easing.linear.

delay (optional)

Number. Specifies the delay, in milliseconds, before the tween begins. Default is 0.

iterations (optional)

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.

reflect (optional)

Boolean. Specifies whether alternate iterations of the tween are reflected (played back in reverse). Default is false.

tag (optional)

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.

id (optional)

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).

delta (optional)

Boolean. Specifies whether non-control parameters are interpreted as final ending values or as changes in value. The default is false.

constantRate (optional)

Number. Specifies the amount of per-second change to an object's position, rotation, alpha, or scale. If you specify this parameter, you must also include the 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 constant-rate interpolations do not adhere to a specific time duration. Also note that constant-rate interpolations that use a non-linear easing function will produce unpredictable results.

constantRateProperty (optional)

String. Indicates which object state governs a constant-rate interpolation. Valid options include "position", "rotation", "alpha", or "scale". This parameter must be specified if you supply the constantRate parameter.

onStart (optional)

Listener. Listener function to be called before the tween begins. This function will receive a reference to the associated Tween as its sole argument.

onComplete (optional)

Listener. Listener function to be called after the tween completes. This function will receive a reference to the associated Tween as its sole argument.

onPause (optional)

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.

onResume (optional)

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.

onCancel (optional)

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.

onRepeat (optional)

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.

onPositionChange (optional)

Listener. Listener function to be called when the tween has its playback position changed manually via animation.setPosition() or object:setPosition().

Examples

Basic Movement
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 } )
Constant Rate Movement
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" } )
Quadrilateral Distortion Tween
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 } )
Fill Effect Property Tween
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 } )
Color Channel Tween
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 } )