DOCSEARCHbyAlgolia
Submit Docs

tween.lua

repository·master·Indexed 20 days ago

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

A lightweight Lua library for property interpolation (tweening) featuring built-in easing functions, support for nested tables, and the ability to define custom easing logic.

Tokens
1.4K
Snippets
6
Records
6
Agent score
21%

What's inside tween.lua

  1. Tweening nested tables

    master

    The tween.lua library supports deep interpolation. If the subject and target tables contain subtables, the library will attempt to tween the values within those subtables.

    Requirement: The 'leaf' values (the actual values being changed) must be numbers in both the subject and the target tables.

    Example:

    -- Fading colors using RGB tables
local properties = { bgcolor = {255, 255, 255}, fgcolor = {0, 0, 0} }
local target = { bgcolor = {0, 0, 0}, fgcolor = {255, 0, 0} }

local fadeTween = tween.new(2, properties, target, 'linear')
    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')

  2. Use built-in easing functions

    master

    Easing functions determine the rate of change during the tween. You can specify them by name as a string or by accessing them via the tween.easing table.

    Default Easing: 'linear'

    Easing Families:

    • linear: Constant speed.
    • quad, cubic, quart, quint, expo, sine, circle: Smooth curves.
    • back: Moves slightly backwards before moving forward.
    • bounce: Simulates bouncing motion.
    • elastic: Simulates inertia/elasticity.

    Variants: Most families support four variants:

    • in: Starts slow, accelerates at the end.
    • out: Starts fast, decelerates at the end.
    • inOut: Starts and ends slow, fast in the middle.
    • outIn: Starts and ends fast, slow in the middle.

    Example usage:

    -- Using a string name
local t1 = tween.new(10, subject, {x=10}, 'outBounce')

-- Using the easing table
local t2 = tween.new(10, subject, {x=10}, tween.easing.outBounce)
    local t1 = tween.new(10, subject, {x=10}, 'outBounce')
local t2 = tween.new(10, subject, {x=10}, tween.easing.outBounce)

  3. Install tween.lua

    master

    To use tween.lua, copy the tween.lua file into your project (for example, into a /lib/ folder) and require it in your Lua scripts. You must capture the returned module in a variable to access its API.

    local tween = require 'tween'

  4. Update and control tweens with tween methods

    master

    Once a tween is created, use the following methods to control its progress:

    t:update(dt)

    Advances the tween by dt (a positive number). This is the primary way to animate. If dt is negative, the tween plays backwards.

    • Returns: true if the tween has reached its duration, false otherwise.

    t:set(clock)

    Sets the tween's internal clock to a specific moment.

    • clock: A positive number or 0.
    • Returns: true if the clock is at or beyond the duration, false otherwise.

    t:reset()

    Resets the internal clock to 0 and restores the subject to its initial state. This is equivalent to t:set(0).

    Note on Time Units: tween.lua has no fixed time units. The units are determined by the dt you pass to update. If you pass seconds, the duration is in seconds; if you pass milliseconds, the duration is in milliseconds.

    -- Advance the tween
local complete = musicTween:update(dt)

-- Jump to a specific time
musicTween:set(5)

-- Restart the tween
musicTween:reset()

  5. Create a new tween with tween.new()

    master

    Use tween.new() to initialize a tween object. This function does not perform the animation itself; it only creates the object. You must call :update(dt) on the returned object in your main loop to drive the animation.

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

    Parameters:

    • duration: A positive number representing how long the transition should take.
    • subject: A table containing the values to be changed. Values must be numbers or tables containing numbers (for nested interpolation).
    • target: A table containing the desired end values. It must contain at least the same keys as subject.
    • easing (optional): A string representing a built-in easing function name (defaults to 'linear') or a custom easing function.

    Example:

    local music = { volume = 0 }
-- Increase volume from 0 to 5 over 10 units of time
local musicTween = tween.new(10, music, {volume = 5})

-- In your update loop:
musicTween:update(dt)
    local musicTween = tween.new(10, music, {volume = 5})
-- ...
musicTween:update(dt)

  6. Create custom easing functions

    master

    You can provide your own easing logic by passing a function to tween.new. The custom function must accept four parameters and return the interpolated value.

    Function Signature: function(t, b, c, d)

    • t (time): Current time (starts at 0, moves towards duration).
    • b (begin): The initial value of the property.
    • c (change): The total change (target value minus initial value).
    • d (duration): The total duration of the tween.

    Example (Bezier Curve):

    local cubicbezier = function (x1, y1, x2, y2) 
  -- (Implementation using a curve engine)
  return function (t, b, c, d) 
    return c * curve:evaluate(t/d) + b 
  end 
end

local labelTween = tween.new(4, label, {y=300}, cubicbezier(.35, .97, .58, .61))
    local my_easing = function(t, b, c, d)
  -- custom math here
  return b + c * (t/d)
end

local t = tween.new(5, subject, {x=100}, my_easing)