Animation

Reference ❯ Animate values and objects using tweens

Animating Values

tween(time, subject, target) top ↑

Syntax

tween( time, subject, target )

tween( time, subject, target, easing )

tween( time, subject, target, easing,
                      callback )

tween( time, subject, target, options,
                      callback )

tween( time, subject, target, options,
                      callback, ... )

tween( time, subject, target, options,
                      callback, ... )

Animates values in subject until they are equal to the key value pairs specified the table target over time seconds. The optional easing type and callback can also be specified.

callback is a function that will be called when the tween has finished animating. Any additional parameters passed to tween are forwarded to the callback function as additional arguments.

tween returns a table that can be used as a unique identifier to identify the tween. This table can be passed to tween.stop and tween.reset.

Note that the easing parameter may be passed in place of the options table, this will assume the default loop type of tween.loop.once. If you would like to specify a custom loop type, then pass a table for options with the keys 'loop' and 'easing' set to the desired values.

time

float, the duration of the tween in seconds.

subject

table or userdata, the object to animate.

target

table, a table of key-value pairs that will be animated in subject, i.e. {x = 10} will animate x to the value 10 in subject.

easing

string or function, an optional easing type for the tween which can be specified as a function or string. There is a complete set of easing functions that fall into the general categories:

linear The default easing function quad, cubic, quart, quint, expo, sine Different variations of smooth acceleration and deceleration back Causes the subject to overshoot and then pull back bounce Causes the subject to hit the target and bounce several times elastic Causes the subject to oscillate like a guitar string around the target

Each easing curve has four variants with the exception of linear

in out inOut outIn

Easing functions a combination of type and variant, such as 'elasticIn', 'quadInOut' and 'backOut'.

These easing functions were adapted from Emmanuel Oga’s easing library

options

table, may contain a loop type specified under the 'loop' key and an easing type specified under the 'easing' key

callback

function, a function to call when this tween has completed

Examples

box = { x = 10, y = 10, width = 20, height = 20, fillColor = color(255) } tween(1, box, {x = 100, y = 100}) tween(1, box, {fillColor = color(255,0,0)}) tween(1, box, {x = 100, y = 100}, tween.easing.quadIn) tween(1, box, {x = 100, y = 100}, tween.easing.linear) tween(1, box, {x = 100, y = 100}, tween.easing.linear, function() print("Tween Ended") end) tween(1, box, {x = 100, y = 100}, tween.easing.linear, function(param) print(param) end, "Tween Ended")

Returns

table, returns a tween identifier that can be used to pause, reset or stop the tween

tween.stop(id) top ↑

Syntax

tween.stop( id )  

Stops the tween specified by id. This does not reset the subject's values to their initial state.

id

table, the id of the tween to stop

Examples

point = { x = 10, y = 10} id = tween(1, point, {x = 100}) tween.stop(id)

tween.stopAll() top ↑

Syntax

tween.stopAll()

Stops all active tweens without resetting them.

Examples

point = { x = 10, y = 10} tween(1, point, {x = 100}) tween(2, point, {x = 200}) -- all tweens will now cease animating tween.stopAll()

tween.reset(id) top ↑

Syntax

tween.reset( id )  

Stops the tween specified by id and resets the subject's values to their initial state.

id

table, the id of the tween to reset

Examples

point = { x = 10, y = 10} id = tween(1, point, {x = 100}) -- point.x will now now return to 10 tween.reset(id)

tween.resetAll() top ↑

Syntax

tween.resetAll()

Resets all active tweens, returning all subject's to their state before the animation.

Examples

point = { x = 10, y = 10} tween(1, point, {x = 100}) tween(2, point, {x = 200}) -- point will now return to {x = 10, y = 10} tween.resetAll()

tween.delay(duration, callback) top ↑

Syntax

tween.delay( duration )
tween.delay( duration, callback )
tween.delay( duration, callback, ... )

This function creates a tween that simply waits for the specified duration. You might use this to create a pause within a tween.sequence, or to delay the calling of a particular function.

Any additional arguments specified after the callback parameter will be passed as arguments to the callback function.

duration

number, the duration of the delay

callback

function, optional callback function

Examples

point = {x = 10, y = 10} t1 = tween(1, point, {x = 100}) -- Create a delay delay = tween.delay(1.0) t2 = tween(1, point, {y = 150}) tween.sequence( t1, delay, t2 )

Returns

table, returns the tween identifier for the delay

tween.sequence( t1, t2, ... ) top ↑

Syntax

tween.sequence( t1, t2, t3, ... )

This function allows you to compose sequences made up of multiple tweens. Each call to the tween function returns an id, tween.sequence accepts a list of these ids and plays them back one after the other.

t1

the id of a tween in the sequence

Examples

point = {x = 10, y = 10} t1 = tween(1, point, {x = 100}) t2 = tween(1, point, {x = 50}) t3 = tween(1, point, {y = 150}) tween.sequence( t1, t2, t3 )

Returns

table, returns the tween identifier for the first tween in the sequence

tween.path( time, subject, targets ) top ↑

Syntax

tween.path( time, subject, targets )

tween.path( time, subject, 
            targets, easing )    

tween.path( time, subject, 
            targets, options )

tween.path( time, subject, 
            targets, options, callback )

tween.path( time, subject, 
            targets, options, 
            callback, ... )
            

tween.path is similar to tween except it accepts an array of target values. The resulting animation interpolates across all the values in targets using a spline.

time

float, the duration of the tween

subject

table or userdata, the object to animate

targets

table, an array of tables containing key-value pairs for each point along the path

options

table, may contain a loop type specified under the 'loop' key and an easing type specified under the 'easing' key

easing

function, one of the easing functions specified in tween.easing

callback

function, triggered when the animation is complete

Examples

point = {x = 10, y = 10} p1 = {x = 10, y = 10} p2 = {x = 100, y = 10} p3 = {x = 100, y = 100} p4 = {x = 10, y = 100 } tween.path( 4.0, point, {p1,p2,p3,p4,p1} )

Returns

table, returns a tween identifier that can be used to pause, reset or stop the tween

Looping Types

tween.loop.once top ↑

Syntax

tween.loop.once

Plays the tween once. This is the default loop type.

tween.loop.forever top ↑

Syntax

tween.loop.forever

Plays the tween over and over again, restarting it each time.

tween.loop.pingpong top ↑

Syntax

tween.loop.pingpong

Plays the tween backwards after it finishes, and then continues to repeat it back and forth.

Easing Types

tween.easing.linear top ↑

Syntax

tween.easing.linear

tween.easing.quadIn top ↑

Syntax

tween.easing.quadIn

tween.easing.quadOut top ↑

Syntax

tween.easing.quadOut

tween.easing.quadInOut top ↑

Syntax

tween.easing.quadInOut

tween.easing.quadOutIn top ↑

Syntax

tween.easing.quadOutIn

tween.easing.cubicIn top ↑

Syntax

tween.easing.cubicIn

tween.easing.cubicOut top ↑

Syntax

tween.easing.cubicOut

tween.easing.cubicInOut top ↑

Syntax

tween.easing.cubicInOut

tween.easing.cubicOutIn top ↑

Syntax

tween.easing.cubicOutIn

tween.easing.quartIn top ↑

Syntax

tween.easing.quartIn

tween.easing.quartOut top ↑

Syntax

tween.easing.quartOut

tween.easing.quartInOut top ↑

Syntax

tween.easing.quartInOut

tween.easing.quartOutIn top ↑

Syntax

tween.easing.quartOutIn

tween.easing.quintIn top ↑

Syntax

tween.easing.quintIn

tween.easing.quintOut top ↑

Syntax

tween.easing.quintOut

tween.easing.quintInOut top ↑

Syntax

tween.easing.quintInOut

tween.easing.quintOutIn top ↑

Syntax

tween.easing.quintOutIn

tween.easing.expoIn top ↑

Syntax

tween.easing.expoIn

tween.easing.expoOut top ↑

Syntax

tween.easing.expoOut

tween.easing.expoInOut top ↑

Syntax

tween.easing.expoInOut

tween.easing.expoOutIn top ↑

Syntax

tween.easing.expoOutIn

tween.easing.sineIn top ↑

Syntax

tween.easing.sineIn

tween.easing.sineOut top ↑

Syntax

tween.easing.sineOut

tween.easing.sineInOut top ↑

Syntax

tween.easing.sineInOut

tween.easing.sineOutIn top ↑

Syntax

tween.easing.sineOutIn

tween.easing.backIn top ↑

Syntax

tween.easing.backIn

tween.easing.backOut top ↑

Syntax

tween.easing.backOut

tween.easing.backInOut top ↑

Syntax

tween.easing.backInOut

tween.easing.backOutIn top ↑

Syntax

tween.easing.backOutIn

tween.easing.bounceIn top ↑

Syntax

tween.easing.bounceIn

tween.easing.bounceOut top ↑

Syntax

tween.easing.bounceOut

tween.easing.bounceInOut top ↑

Syntax

tween.easing.bounceInOut

tween.easing.bounceOutIn top ↑

Syntax

tween.easing.bounceOutIn

tween.easing.elasticIn top ↑

Syntax

tween.easing.elasticIn

tween.easing.elasticOut top ↑

Syntax

tween.easing.elasticOut

tween.easing.elasticInOut top ↑

Syntax

tween.easing.elasticInOut

tween.easing.elasticOutIn top ↑

Syntax

tween.easing.elasticOutIn