animation.newTimeline()

timelineParams _^(required)

Table. A table which specifies the child tweens, markers, and other parameters for the timeline — see the next section for details.

tweens _^(required)

Table. A table containing child tables, each specifying a tween to be included in the timeline. Each of these tables 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 tween should be configured similarly to animation.to(), containing the target object to animate along with properties and parameters.
• useFrom — Optional boolean property which, if set to true, will make the tween behave as if it were declared by animation.from().

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

    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 _^(optional)

Table. An optional table of time markers to associate with the timeline. These markers allow you to specify named jump-to points within the timeline. Each should be defined as a table which may contain the following properties:

• name — A string name to associate with the marker. This name can be used to reference the marker in other commands such as object:setPosition() and animation.setPosition(). 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 a timeline:

    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
    }

autoPlay _^(optional)

Boolean. If true, the timeline will begin playing immediately. Default is false.

tag _^(optional)

String. Specifies the timeline tag. The animation library can pause, resume, cancel, set the position, or change the speed scale of timelines sharing the same tag.

id _^(optional)

String. An optional identification string to assign to the timeline. This can be retrieved as obj.id from any of the timeline event listener functions (see below).

delay _^(optional)

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

speedScale _^(optional)

Number. Adjusts the relative speed scale for the timeline. 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.

autoCancel _^(optional)

Boolean. If set to true, all child tweens (and the timeline itself) will be cancelled upon completion of the timeline. This should only be done if you don't intend to replay the timeline again after its first play through. Default is false.

onStart _^(optional)

Listener. Listener function to be called directly before the timeline begins. This function will receive a reference to the associated Timeline object as its sole argument.

onComplete _^(optional)

Listener. Listener function to be called after the timeline completes. This function will receive a reference to the associated Timeline object as its sole argument.

onPause _^(optional)

Listener. Listener function to be called when the timeline is paused. This function will receive a reference to the associated Timeline object as its sole argument.

onResume _^(optional)

Listener. Listener function to be called when the timeline is resumed. This function will receive a reference to the associated Timeline object as its sole argument.

onCancel _^(optional)

Listener. Listener function to be called when the timeline is cancelled. This function will receive a reference to the associated Timeline object as its sole argument.

onPositionChange _^(optional)

Listener. Listener function to be called when the timeline has its playback position changed manually via object:setPosition() or animation.setPosition(). This function will receive a reference to the associated Timeline object as its sole argument.

onMarkerPass _^(optional)

Listener. Listener function to be called when a marker within the timeline is reached/passed. This function will receive a table containing a reference to the associated Timeline object (timeline), along with the name property and optional params table that was assigned to the specific marker.