wolfhacklua API 1.1 Forum

anim

Easing curves, frame-rate independent smoothing, tweens and springs for animating values.

since 1.0no permission needed

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): number

Applies an easing curve.

ParameterTypeDescription
namestringAn easing name from anim.names.
tnumberProgress from 0 to 1.
ReturnsDescription
numberThe eased progress. Back and elastic curves overshoot 0..1.

anim.approach#since 1.0

anim.approach(current: number, target: number, rate: number, dt: number): number

Moves a value toward a target with frame-rate independent smoothing: the same motion at 60 or 240 fps.

ParameterTypeDescription
currentnumberThe value now.
targetnumberThe value to move toward.
ratenumberHow fast; larger is faster.
dtnumberSeconds since the last step (time.dt()).
ReturnsDescription
numberThe new value.
lua
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): number

Linear interpolation.

ParameterTypeDescription
anumberStart.
bnumberEnd.
tnumberProgress 0..1.
ReturnsDescription
numbera + (b - a) * t.

anim.tween#since 1.0

anim.tween(options: table): Tween

Animates a number from from to to. Read tw.value in a draw handler or react in on_update.

ParameterTypeDescription
optionstable{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.
ReturnsDescription
TweenA tween object, see below.
lua
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): Spring

A spring that chases a target value; it overshoots and settles. Set the target with sp:target(v).

ParameterTypeDescription
initialnumberThe starting value.
options optionaltable{stiffness = 170, damping = 26, on_update}. default stiffness 170, damping 26
ReturnsDescription
SpringA spring object, see below.
lua
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.

FieldTypeDescription
valuenumberThe current value.
donebooleantrue 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.

FieldTypeDescription
valuenumberThe current value.
velocitynumberThe current speed.

sp:target#since 1.0

sp:target(v: number)

Sets the value the spring moves toward.

ParameterTypeDescription
vnumberThe new target.

sp:snap#since 1.0

sp:snap(v: number)

Jumps to a value with no motion.

ParameterTypeDescription
vnumberThe value.

sp:stop#since 1.0

sp:stop()

Stops the spring.

API 1.1 · source docs-src/api/anim.json