Animation — Tweens and Timelines

Tween Target

The first argument in either function, target, will most often be a display object or display group that you wish to animate. However, for more specialized cases, it can also be a RectPath point for quadrilateral distortion, a table of RGB+A color channels for a Paint fill, or a fill.effect property.

Object Properties

The second argument, properties, is a table of key-value pairs. Inside this table, specify each desired property to change along with its final value (starting value if using animation.from()).

Control Parameters

The third argument, params, is also a table of key-value pairs. Inside this table, specify the appropriate control parameters for the tween:

Easing Functions

By default, tweens occur at a consistent, linear rate of change from start to end. However, you may wish to use an easing effect to achieve a different result, for example, to make an object move quickly at the start and gradually slow down as it reaches its destination. This behavior can be achieved using an easing function in conjunction with the animation call.

To set an easing effect on a tween, simply provide the easing key in the params table with a value equal to one of the easing library functions. For example:

-- Tween the object using outward quadratic interpolation
animation.to( myObject,
    { y=100 },
    {
        time = 2000,
        easing = easing.outQuad
    }
)

-- Tween the object using inward and then outward exponential interpolation
animation.to( myObject,
    { y=100 },
    {
        time = 2000,
        easing = easing.inOutExpo
    }
)

Tween Events

Tweens also support a full range of tween events as listed below. These should be specified as key-value pairs within the params table. When the event occurs, the associated listener function will receive a reference to the Tween object.

In the following example, the tweenListener() function will be called when the tween completes:

local myObject = display.newRect( 0, 0, 100, 100 )

local function tweenListener( obj )
    print( "Tween completed; ID: " .. obj.id )
end

animation.to( myObject,
    { alpha=0 },
    {
        time = 2000,
        id = "tween1",
        onComplete = tweenListener
    }
)

Timeline Tweens

At the minimum, the timelineParams table must contain a child table, tweens, which contains all of the tweens that will be involved in the timeline:

local newTimeline = animation.newTimeline(
{
    tweens = {},
})

Inside the tweens table, individual tweens are configured via basic Lua tables that accept the following key-value pairs:

• startTime — Optional number of milliseconds into the timeline progression at which the tween should start. Default is 0 (start of the timeline).
• tween — Required table which configures the tween. This should be configured similarly to any basic tween (see Tweens above).
• useFrom — Optional boolean property which, if set to true, will make the tween behave as if it were declared by animation.from() instead of animation.to().

For example, this tweens table configures two individual tweens for a timeline:

local newTimeline = animation.newTimeline(
{
    tweens = {
        { startTime=0, tween={ object1, { x=400 }, { time=4000, iterations=5, reflect=true } } },
        { startTime=1000, tween={ object1, { y=400 }, { time=4000, easing=easing.outQuad } } }
    },
})

Timeline Markers

For an added level of control, you can specify any number of markers within the timeline duration. These markers, specified within the optional markers table, allow you to specify jump-to points within the timeline. Each marker should be defined as a table containing the following properties:

• name — A string name to associate with the marker. This name should be unique (you should not use duplicate marker names within the same timeline).
• time — The number of milliseconds into the timeline progression at which to set the marker.
• params — An optional table which can contain custom information; this table will be passed to the onMarkerPass listener function (details).

For example, this markers table configures three time markers for the timeline:

local newTimeline = animation.newTimeline(
{
    tweens = {
        { startTime=0, tween={ object1, { x=400 }, { time=4000, iterations=5, reflect=true } } },
        { startTime=1000, tween={ object1, { y=400 }, { time=4000, easing=easing.outQuad } } }
    },
    markers = {
        { name="marker_start", time=0 },    -- Start of the timeline
        { name="marker_2000", time=2000 },  -- 2 seconds into the timeline
        { name="marker_3000", time=3000 }   -- 3 seconds into the timeline
    },
})

Other Parameters

Timelines accept a variety of additional parameters (optional) which can be used for fine-tuned setup and control. These should be specified as key-value pairs within the timelineParams table.

Timeline Events

Timelines also support a full range of timeline events as listed below. These should be specified as key-value pairs within the timelineParams table. When the event occurs, the associated listener function will receive a reference to the Timeline object.

In the following example, the timelineListener() function will be called when every iteration of every tween in the timeline completes:

local object1 = display.newRect( 50, 50, 100, 100 )

local function timelineListener( obj )
    print( "Timeline completed; ID: " .. obj.id )
end

-- Create a timeline object
local newTimeline = animation.newTimeline(
{
    tweens = {
        { startTime=0, tween={ object1, { x=400 }, { time=4000, iterations=5, reflect=true } } },
        { startTime=1000, tween={ object1, { y=400 }, { time=4000, easing=easing.outQuad } } }
    },
    id = "timeline1",
    onComplete = timelineListener
})

-- Set the timeline playing
newTimeline:resume()