anim
Easing curves, frame-rate independent smoothing, tweens and springs for animating values.
Animation objects (tween, spring) are advanced by the host every frame; they stop when the script stops. For a value that simply follows a target, anim.approach called from a draw handler is the cheapest option.
Reference#
anim.names#since 1.0
anim.names: string[]The easing names anim.ease accepts: linear, in_quad, out_quad, inout_quad, in_cubic, out_cubic, inout_cubic, in_sine, out_sine, inout_sine, in_expo, out_expo, inout_expo, in_back, out_back, inout_back, out_elastic, out_bounce.
anim.ease#since 1.0
anim.ease(name: string, t: number): numberApplies an easing curve.
| Parameter | Type | Description |
|---|---|---|
name | string | An easing name from anim.names. |
t | number | Progress from 0 to 1. |
| Returns | Description |
|---|---|
number | The eased progress. Back and elastic curves overshoot 0..1. |
anim.approach#since 1.0
anim.approach(current: number, target: number, rate: number, dt: number): numberMoves a value toward a target with frame-rate independent smoothing: the same motion at 60 or 240 fps.
| Parameter | Type | Description |
|---|---|---|
current | number | The value now. |
target | number | The value to move toward. |
rate | number | How fast; larger is faster. |
dt | number | Seconds since the last step (time.dt()). |
| Returns | Description |
|---|---|
number | The new value. |
local shown = 0
events.on("draw", function()
shown = anim.approach(shown, store.get("on", false) and 1 or 0, 12, time.dt())
draw.rect(20, 20, 100 * shown, 8, 0xFFFFFFFF)
end)anim.lerp#since 1.0
anim.lerp(a: number, b: number, t: number): numberLinear interpolation.
| Parameter | Type | Description |
|---|---|---|
a | number | Start. |
b | number | End. |
t | number | Progress 0..1. |
| Returns | Description |
|---|---|
number | a + (b - a) * t. |
anim.tween#since 1.0
anim.tween(options: table): TweenAnimates a number from from to to. Read tw.value in a draw handler or react in on_update.
| Parameter | Type | Description |
|---|---|---|
options | table | {from, to, duration, ease, delay, loop, on_update, on_done}: numbers for from, to, duration (seconds) and delay; ease is a name from anim.names; loop is true or "pingpong"; on_update(v) and on_done() are functions. |
| Returns | Description |
|---|---|
Tween | A tween object, see below. |
local tw = anim.tween{ from = 0, to = 1, duration = 0.4, ease = "out_cubic" }
events.on("draw", function()
draw.rect(20, 20, 200 * tw.value, 10, 0xFFFFFFFF)
end)anim.spring#since 1.0
anim.spring(initial: number, options?: table): SpringA spring that chases a target value; it overshoots and settles. Set the target with sp:target(v).
| Parameter | Type | Description |
|---|---|---|
initial | number | The starting value. |
options optional | table | {stiffness = 170, damping = 26, on_update}. default stiffness 170, damping 26 |
| Returns | Description |
|---|---|
Spring | A spring object, see below. |
local sp = anim.spring(0)
sp:target(1)
events.on("draw", function() draw.circle(100, 100 + 50 * sp.value, 8, 0xFFFFFFFF) end)Tween#
Returned by anim.tween.
| Field | Type | Description |
|---|---|---|
value | number | The current value. |
done | boolean | true when a non-looping tween has finished. |
tw:stop#since 1.0
tw:stop()Stops the tween where it is.
tw:restart#since 1.0
tw:restart()Starts the tween again from the beginning.
Spring#
Returned by anim.spring.
| Field | Type | Description |
|---|---|---|
value | number | The current value. |
velocity | number | The current speed. |
sp:target#since 1.0
sp:target(v: number)Sets the value the spring moves toward.
| Parameter | Type | Description |
|---|---|---|
v | number | The new target. |
sp:snap#since 1.0
sp:snap(v: number)Jumps to a value with no motion.
| Parameter | Type | Description |
|---|---|---|
v | number | The value. |
sp:stop#since 1.0
sp:stop()Stops the spring.