• Stars
    star
    568
  • Rank 78,502 (Top 2 %)
  • Language
    Lua
  • License
    Other
  • Created over 13 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tweening/Easing/Interpolating functions for lua. Inspired on jQuery's animate method.

tween.lua

Build Status Coverage Status

tween.lua is a small library to perform tweening in Lua. It has a minimal interface, and it comes with several easing functions.

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" }
local musicTween = tween.new(10, music, {volume = 5})
...
musicTween:update(dt)

-- 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" }
local labelTween = tween.new(4, label, {y=300}, 'outBounce')
...
labelTween:update(dt)

-- fade background from white to black and foregrond from black to red in 2 seconds
-- Notice that you can use subtables with tween
local properties = {bgcolor = {255,255,255}, fgcolor = {0,0,0}}
local fadeTween = tween.new(2, properties, {bgcolor = {0,0,0}, fgcolor={255,0,0}}, 'linear')
...
fadeTween:update(dt)

Demo

There is a demo in the "demo" branch of this repo:

https://github.com/kikito/tween.lua/tree/demo

demo image

You will need LÖVE to execute the demo.

In the animation above, you can see how the user can move time "forwards or backwards" by pressing and releasing the space key.

Interface

Tween creation

local t = tween.new(duration, subject, target, [easing])

Creates a new tween.

  • duration means how much the change will take until it's finished. It must be a positive number.
  • subject must be a table with at least one key-value. Its values will be gradually changed by the tween until they look like target. All the values must be numbers, or tables with numbers.
  • target must be a table with at least the same keys as subject. Other keys will be ignored.
  • easing can be either a function or a function name (see the easing section below). It's default value is 'linear'
  • t is the object that must be used to perform the changes - see the "Tween methods" section below.

This function only creates and returns the tween. It must be captured in a variable and updated via t:update(dt) in order for the changes to take place.

Tween methods

local complete = t:update(dt)

Gradually changes the contents of subject to that it looks more like target as time passes.

  • t is a tween returned by tween.new
  • dt must be positive number. It will be added to the internal time counter of the tween. Then subject's values will be updated so that they approach target's using the selected easing function.
  • complete is true if the tween has reached its limit (its internal clock is >= duration). It is false otherwise.

When the tween is complete, the values in subject will be equal to target's. The way they change over time will depend on the chosen easing function.

If dt is positive, the easing will be applied until the internal clock equals t.duration, at which point the easing will stop. If it is negative, the easing will play "backwards", until it reaches the initial value.

This method is roughtly equivalent to t:set(self.clock + dt).

local complete = t:set(clock)

Moves a tween's internal clock to a particular moment.

  • t is a tween returned by tween.new
  • clock is a positive number or 0. It's the new value of the tween's internal clock.
  • complete works like in t:update; it's true if the tween has reached its end, and false otherwise.

If clock is greater than t.duration, then the values in t.subject will be equal to t.target, and t.clock will be equal to t.duration.

t:reset()

Resets the internal clock of the tween back to 0, resetting subject.

  • t is a tween returned by tween.new

This method is equivalent to t:set(0).

Easing functions

Easing functions are functions that express how slow/fast the interpolation happens in tween.

tween.lua comes with 45 default easing functions already built-in (adapted from Emmanuel Oga's easing library).

tween families

The easing functions can be found in the table tween.easing.

They can be divided into several 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
Circ inCirc outCirc inOutCirc outInCirc
Back inBack outBack inOutBack outInBack
Bounce inBounce outBounce inOutBounce outInBounce
Elastic inElastic outElastic inOutElastic outInElastic

When you specify an easing function, you can either give the function name as a string. The following two are equivalent:

local t1 = tween.new(10, subject, {x=10}, tween.easing.linear)
local t2 = tween.new(10, subject, {x=10}, 'linear')

But since 'linear' is the default, you can also do this:

local t3 = tween.new(10, subject, {x=10})

Custom easing functions

You are not limited to tween's easing functions; if you pass a function parameter in the easing, it will be used.

The passed function will need to take 4 parameters:

  • t (time): starts in 0 and usually moves towards duration
  • b (begin): initial value of the of the property being eased.
  • c (change): ending value of the property - starting value of the property
  • d (duration): total duration of the tween

And must return the new value after the interpolation occurs.

Here's an example using LÖVE's Bezier Curve (you will need LÖVE for this example, but tween.lua does not need LÖVE in general).

local cubicbezier = function (x1, y1, x2, y2)
  local curve = love.math.newBezierCurve(0, 0, x1, y1, x2, y2, 1, 1)
  return function (t, b, c, d) return c * curve:evaluate(t/d) + b end
end

local label = { x=200, y=0, text = "hello" }
local labelTween = tween.new(4, label, {y=300}, cubicbezier(.35, .97, .58, .61))

Gotchas / Warnings

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

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'

You can of course specify your own easing function. Just make sure you respect the parameter format.

Specs

This project uses busted for its specs. In order to run them, install busted, and then execute it on the top folder:

busted

Credits

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

https://github.com/emmanueloga/easing

See the LICENSE.txt file for details.

Changelog

See CHANGELOG.md for a full list of changes.

More Repositories

1

middleclass

Object-orientation for Lua
Lua
1,629
star
2

inspect.lua

Human-readable representation of Lua tables
Lua
1,346
star
3

bump.lua

A collision detection library for Lua
Lua
914
star
4

anim8

An animation library for LÖVE
Lua
707
star
5

lua_missions

Lua Koans, minus the Zen stuff
Lua
375
star
6

md5.lua

MD5 sum in pure Lua, with no C and no external dependencies
Lua
321
star
7

love-tile-tutorial

A tutorial for making tile-based games with LÖVE
Lua
272
star
8

i18n.lua

A very complete i18n lib for Lua
Lua
251
star
9

gamera

A camera system for LÖVE
Lua
248
star
10

stateful.lua

Stateful classes for Lua
Lua
174
star
11

cron.lua

Time-related functions for Lua, inspired in javascript's setTimeout and setInterval
Lua
169
star
12

love-loader

Threaded resource loading for LÖVE
Lua
130
star
13

lua-sandbox

A lua sandbox for executing non-trusted code
Lua
128
star
14

beholder.lua

Minimal observer pattern for Lua, with a couple twists
Lua
105
star
15

semver.lua

Semantic versioning for Lua
Lua
103
star
16

memoize.lua

memoized functions in lua
Lua
88
star
17

sha1.lua

(Deprecated Repo) SHA-1 secure hash computation, and HMAC-SHA1 signature computation in Lua (5.1)
Lua
72
star
18

7-languages-in-7-weeks

My personal repo for 7LI7W exercises
Prolog
63
star
19

luv.js

Minimal HTML5 game development lib
JavaScript
43
star
20

passion

An object-oriented LÖVE game engine
Lua
36
star
21

middleclass-extras

A set of middleclass add-ons that make it easier to use in some cases
Lua
32
star
22

bresenham.lua

Lua
29
star
23

utf8_validator.lua

Easily validating UTF-8 strings in pure Lua
Lua
26
star
24

battle-cry

Lua
13
star
25

middleclass-commons

Interface between middleclass and Class-Commons
Lua
10
star
26

pulsar.lua

A-star algorithm implementation in Lua
Lua
10
star
27

ekrixion

simple game in LÖVE
Lua
9
star
28

fay

A small game for LÖVE, made for Ludum Dare #25
Lua
9
star
29

contact.php

Simple contact form. I really mean it. It's very simple.
PHP
9
star
30

lua-for-javascripters

A presentation about Lua, for people who are familiar with Javascript
CSS
7
star
31

pew-pew-boom

Explosions in 2D space. Ussing PÄSSION and LÖVE
Lua
6
star
32

middleclass-specs

Specs for testing middleclass
Lua
5
star
33

kongame

Lua
5
star
34

nvim

nvim custom config
Vim Script
5
star
35

missing_i18n

Rails mountable engine that finds missing i18n translations and displays them in a variety of formats.
Ruby
5
star
36

busted-stable

A simple rock to install a stable version of busted
4
star
37

middleclass-ai

Ai-related classes implemented in Lua
4
star
38

passion-demos

several demos of the PÄSSION game engine
Lua
4
star
39

rickshaw-vs-nvd3

Comparison of 2 popular js charting libs
CSS
3
star
40

adegan

my personal vim configuration
Vim Script
3
star
41

ci-with-lua

Presentation about continuous integration with Lua
CSS
3
star
42

love_open_chars

open_chars used on a love
Lua
3
star
43

us-4-es.keylayout

Mac keyboard layout for users of U.S. layout who need to write Spanish characters occasionally.
3
star
44

things-to-do-with-postgresql

A presentation about postgresql and rails
CSS
3
star
45

measuring-luas-performance

CSS
2
star
46

a-taste-of-lua

My talk about Lua in APIStrat Chicago 09-2014
CSS
2
star
47

stateful-demo

A simple demo of stateful.lua
Lua
2
star
48

rust-by-example

My activities & impressions while reading Rust by Example
Rust
2
star
49

modis.lua

Lua implementation of MongoDB query language over redis.
Lua
2
star
50

open_chars

My take on Silveira Neto's Open Charas project
2
star
51

jay

javascript object oriented game engine
JavaScript
2
star
52

ld-30

LD 30 - Earth, Hell & Space
Lua
2
star
53

kiki.to

CSS
1
star
54

S021

Interactive Fiction Collaborative Story
HTML
1
star
55

ood-with-ruby

A POODR-based presentation
CSS
1
star
56

stimulus-how-and-why

CSS
1
star
57

lua-for-rubyists

Slides for a talk about Lua for Ruby practicioners
CSS
1
star
58

hacking-madrid

Presentation for t3chfest 2016 about my work in decide.madrid.es
CSS
1
star
59

ci-with-ruby

Talk about continouous integration with ruby
CSS
1
star
60

popular-gemology

A talk about ruby gems: what to look for and to avoid
CSS
1
star
61

old-blog

Kikito's github page
JavaScript
1
star
62

api-addicts-2021-06-24

Companion repo for my API:Addicts talk of June 2021
1
star