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 and target must both be tables. tween.start will gradually alter @subject@’s properties until they look like in target. Properties not mentioned in target 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 to tween.start
tween.stop([id]) stops the animation identified by id. It does not reset the animation to its initial state.
tween.stopAll() stops all animations, without resetting any values
tween.reset(id) stops the animation identified by id, and resets its subject 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. When tween.update is executed, the values of very subject 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 to tween.update
tween does not have any defined time units (seconds, milliseconds, etc). You define the units it uses by passing it a dt on tween.update. If dt is in seconds, then tween will work in seconds. If dt is in milliseconds, then tween 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 and circle 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 end
out starts fast, and decelerates at the end
inOut starts and ends slow, but it’s fast in the middle
outIn 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.

maximgavrilov / tween.lua