tween.lua
Small sets of functions for performing tweening in Lua. Based on jQuery’s animate function
Examples
local tween = require 'tween' -- increase the volume of music from 0 to 5 in 10 seconds local music = { volume = 0, path = "path/to/file.mp3" } tween(10, music, { volume = 5 }) -- make some text fall from the top of the screen, bouncing on y=300, in 4 seconds local label = { x=200, y=0, text = "hello" } tween(4, label, { y=300 }, 'outBounce') -- fade background to black in 2 seconds, and then print a message on the terminal local backgroundColor = {255,255,255} tween(2, backgroundColor, {0,0,0}, 'linear', print, "hello!")
You will need to put tween.update
somewhere in your game loop update function:
function your_game_loop_update(dt) ... tween.update(dt) ... end
Interface
tween.start(time, subject, target, [easing], [callback], ...)
. By default it Returns an identifier (id
)time
will specify how much time must the change will take.subject
andtarget
must both be tables.tween.start
will gradually alter @subject@’s properties until they look like intarget
. Properties not mentioned intarget
will be ignored.easing
can be either a function or a function name (see the easing section below). It’s default value is'linear'
callback
is a function to be called when the tween is over. Only callable objects such as functions are acceptable here. Can be nil.- Any other parameters are passed to the
callback
as additional parameters.
tween(time, subject, target, [easing], [callback])
redirect totween.start
tween.stop([id])
stops the animation identified byid
. It does not reset the animation to its initial state.tween.stopAll()
stops all animations, without resetting any valuestween.reset(id)
stops the animation identified byid
, and resets itssubject
to the initial values it had at the start of the animation.tween.resetAll()
resetd all currently playing animations to their initial state.tween.update(dt)
is needed to be executed on the main program loop.dt
is the amount of time that has passed since the last iteration. Whentween.update
is executed, the values of verysubject
are slightly modified so they resemble a bit more their @target@s. It is also the time in which the callbacks are invoked, if they exist.
Gotchas / Warnings
tween
does not implement any hardware or software clock; you will have to provide it with the access to the hardware timers, in the form of periodic calls totween.update
tween
does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it adt
ontween.update
. Ifdt
is in seconds, thentween
will work in seconds. Ifdt
is in milliseconds, thentween
will work in milliseconds.tween
can work on deeply-nested subtables (the “leaf” values have to be numbers in both the subject and the target)
local trafficLight = { color1 = {255,0,0}, color2 = {0,0,0}, color3 = {0,0,0} } tween(3, trafficLight, { color1 = {0,0,0}, color2 = {255,255,0}, color3 = {0,0,0} }, 'linear', function() tween(1, trafficLight, { color1 = {0,0,0}, color2 = {0,0,0}, color3 = {0,255,0} } end) for i=1, 4 do tween.update(1) -- In 3 iterations the lights will change from red to yellow. The last iteration will change them to green end
Installation
Just copy the tween.lua file somewhere in your projects (maybe inside a /lib/ folder) and require it accordingly.
Remember to store the value returned by require somewhere! (I suggest a local variable named tween)
local tween = require 'tween'
The second step is making sure that your “game loop” calls tween.update
with a proper dt
. Where to put this call depends greatly on your game loop architecture. It will probably go into an “update” function:
function update(dt) ... tween.update(dt) end
Also, make sure to read the license file; the text of that license file must appear somewhere in your projects’ files.
Easing functions
Easing functions are functions that express how slow/fast the interpolation happens in tween.
tween.lua comes with a lot of easing functions already built-in (adapted from Emmanuel Oga’s easing library
They can be divided into several big families:
linear
is the default interpolation. It’s the simplest easing function.quad
,cubic
,quart
,quint
,expo
,sine
andcircle
are all “smooth” curves that will make transitions look natural.- The
back
family starts by moving the interpolation slightly “backwards” before moving it forward. - The
bounce
family simulates the motion of an object bouncing. - The
elastic
family simulates inertia in the easing, like an elastic gum.
Each family (except linear
) has 4 variants:
in
starts slow, and accelerates at the endout
starts fast, and decelerates at the endinOut
starts and ends slow, but it’s fast in the middleoutIn
starts and ends fast, but it’s slow in the middle
family | in | out | inOut | outIn |
---|---|---|---|---|
linear | linear | linear | linear | linear |
quad | inQuad | outQuad | inOutQuad | outInQuad |
cubic | inCubic | outCubic | inOutCubic | outInCubic |
quart | inQuart | outQuart | inOutQuart | outInQuart |
quint | inQuint | outQuint | inOutQuint | outInQuint |
expo | inExpo | outExpo | inOutExpo | outInExpo |
sine | inSine | outSine | inOutSine | outInSine |
circle | inCirc | outCirc | inOutCirc | outInCirc |
back | inBack | outBack | inOutBack | outInBack |
bounce | inBounce | outBounce | inOutBounce | outInBounce |
elastic | inElastic | outElastic | inOutElastic | outInElastic |
You may want to give a look to the graphs folder on this repository to get a better idea of what I’m talking about.
When you specify an easing fucntion, you can either give the function name as a string. The following two are equivalent:
tween(10, subject, {x=10}, tween.easing.linear) tween(10, subject, {x=10}, 'linear')
Well, actually, since ‘linear’ is the default, you can also do this:
tween(10, subject, {x=10})
You can of course specify your own easing function. Just make sure you respect the parameter format.
Specs
This project uses telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just enter the tween.lua folder and run:
tsc spec/*
Credits
The easing functions have been copied from EmmanuelOga’s project in
https://github.com/emmanueloga/easing
See the LICENSE.txt file for details.