Animation

Animating Values

tween(time, subject, target)
tween.stop(id)
tween.stopAll()
tween.reset(id)
tween.resetAll()
tween.play(id)
tween.delay(duration, callback)
tween.sequence( t1, t2, ... )
tween.path( time, subject, targets )

Looping Types

tween.loop.once
tween.loop.forever
tween.loop.pingpong

Easing Types

tween.easing.linear
tween.easing.quadIn
tween.easing.quadOut
tween.easing.quadInOut
tween.easing.quadOutIn
tween.easing.cubicIn
tween.easing.cubicOut
tween.easing.cubicInOut
tween.easing.cubicOutIn
tween.easing.quartIn
tween.easing.quartOut
tween.easing.quartInOut
tween.easing.quartOutIn
tween.easing.quintIn
tween.easing.quintOut
tween.easing.quintInOut
tween.easing.quintOutIn
tween.easing.expoIn
tween.easing.expoOut
tween.easing.expoInOut
tween.easing.expoOutIn
tween.easing.sineIn
tween.easing.sineOut
tween.easing.sineInOut
tween.easing.sineOutIn
tween.easing.backIn
tween.easing.backOut
tween.easing.backInOut
tween.easing.backOutIn
tween.easing.bounceIn
tween.easing.bounceOut
tween.easing.bounceInOut
tween.easing.bounceOutIn
tween.easing.elasticIn
tween.easing.elasticOut
tween.easing.elasticInOut
tween.easing.elasticOutIn

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, tween.reset and tween.play. Note that tweens play by default upon initialization.

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 stop, reset or play 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.play(id) top ↑

Syntax

tween.play( id )

Plays 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 play

Examples

point = { x = 10, y = 10} id = tween(1, point, {x = 100}) function pauseTween(id) tween.stop(id) end function resumeTween(id) tween.play(id) end

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