tween

Tween / easing library — smooth property interpolation with chaining, timelines, and 30+ easing curves. This file is the public surface; the implementation lives in three submodules: core.module/ (lifecycle and interpolation), easing.module/ (easing curves and name lookup), and timeline.module/ (keyframe sequencer).

Important: callers MUST call tween.update(dt) every frame from a component's update function. Without this, tweens will not advance.

Exports

Property animation:

• tween.to(entityId, property, target, durationOrOpts, easing?) -> Tween — animate an entity property to a target value.
• tween.fromTo(fromVal, toVal, durationOrOpts, easing?) -> Tween — animate raw values via onUpdate.
• tween.create(opts: TweenOpts) -> Tween — create without auto-starting (for use in chains / timelines).
• tween.update(dt: number) — advance all active tweens; call every frame.

Global controls:

• tween.setGlobalSpeed(speed: number) / tween.getGlobalSpeed() -> number.
• tween.cancelAll(), tween.cancelEntity(entityId).
• tween.pauseAll(), tween.resumeAll().
• tween.getActiveCount() -> number.

Timelines and easing:

• tween.timeline() -> Timeline — keyframe-based orchestration.
• tween.easing — the easing namespace (re-export of the easing module).
• tween.easings() -> { string } — list of available easing names.

Types:

• TweenOpts = { entityId?, property?, from?, to?, duration?, delay?, easing?, loops?, yoyo?, onStart?, onUpdate?, onComplete?, onCancel?, onLoop? }

Usage

local tween = require("@builtin::modules.tween")

-- Drive the tween system every frame from a component update:
function update(dt)
    tween.update(dt)
end

-- Property tween on an entity:
tween.to("box", "position", { x = 0, y = 5, z = 0 }, {
    duration = 1.0,
    easing = "easeOutBounce",
    onComplete = function() print("done") end,
})

-- Raw value tween via callback:
tween.fromTo(0, 1, 0.4, "easeInOutQuad"):andThen(
    tween.create({ from = 1, to = 0, duration = 0.4, easing = "easeOutCubic" })
)

-- Timeline sequencer:
local tl = tween.timeline()
tl:add(0.0, tween.create({ entityId = e, property = "position", to = pos, duration = 1 }))
tl:add(0.5, tween.create({ entityId = e, property = "tint", to = color, duration = 0.3 }))
tl:play()

function update(dt)
    tween.update(dt)
    tl:update(dt)
end

Notes

• Properties supported by tween.to: "position", "rotation", "scale", "tint". See core.module/init.luau ENTITY_PROPS for the full accessor map.
• Duration argument is permissive — pass a number (seconds) or a full TweenOpts table with duration, easing, delay, loops, yoyo, and the callback hooks.
• Tween / Timeline objects are returned as the underlying class instances from the core / timeline submodules; the public M.timeline() surface exposes them as plain TimelineObj and TweenObj opaque handles to keep --!global registration unencumbered.
• The submodules are also independently require-able for callers that need direct access to easing curves or timeline internals.