Small sets of functions for performing tweening in Lua. Based on jQuery’s animate function

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

• 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.

• 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

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

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.

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/*

The easing functions have been copied from EmmanuelOga’s project in

https://github.com/emmanueloga/easing

See the LICENSE.txt file for details.