animation.to()

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:

• Properties of a display object such as x, y, rotation, alpha, xScale, yScale, width, height, anchorX, anchorY, maskX, maskY, maskScaleX, and maskScaleY.
• Font size of a TextObject created via display.newText().
• Properties related to quadrilateral distortion of a RectPath, applicable only to a ShapeObject. These include x1, y1, x2, y2, x3, y3, x4, and y4. See here for more information.
• RGB+A color channels (r, g, b, and a), applicable only if the target is the .fill table of a ShapeObject.
• A filter effect property associated with a specific filter effect, applicable only to the object’s fill.effect property. See here for details on which filter parameters apply to each filter effect.

params _^(required)

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

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

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