timeline

Timeline sequencer — keyframe-based orchestration of multiple tweens. Each Timeline holds a list of { time, tween } entries; calling timeline:update(dt) advances the elapsed clock, starts entries whose time has arrived, and steps every started tween.

Returned by tween.timeline() from the parent module — user code normally doesn't require this submodule directly.

Exports

Construction:

• Timeline.new() -> Timeline — create a new pending timeline.

Instance methods (chainable except update and the getters):

• tl:add(time: number, tweenOrOpts) -> Timeline — schedule a tween at a time offset (seconds from :play()).
• tl:play() -> Timeline — start running. Resets elapsed time, loop counter, reverse flag.
• tl:update(dt: number) — advance one frame. Call from your component's update(dt).
• tl:pause() -> Timeline / tl:resume() -> Timeline / tl:cancel() -> Timeline — lifecycle.
• tl:setSpeed(speed) -> Timeline — playback speed multiplier.
• tl:setLoops(count, yoyo?) -> Timeline — loop count (0 for infinite) + optional yoyo.
• tl:setOnComplete(fn) -> Timeline / tl:setOnLoop(fn) -> Timeline — callbacks.
• tl:getState() -> string, tl:getElapsed() -> number, tl:getDuration() -> number, tl:getProgress() -> number.

Types:

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

Usage

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

tl:add(0.0, tween.create({
    entityId = "box",
    property = "position",
    to       = { x = 0, y = 5, z = 0 },
    duration = 1.0,
    easing   = "easeOutCubic",
}))
tl:add(0.5, tween.create({
    entityId = "box",
    property = "tint",
    to       = { r = 1, g = 0, b = 0, a = 1 },
    duration = 0.3,
}))

tl:setOnComplete(function() print("sequence done") end)
tl:play()

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

Notes

• :add accepts either a Tween (returned by tween.create) or a raw TweenOpts table — the latter is converted via Core.create (no auto-start). Either way the tween starts when the timeline reaches its scheduled time.
• Total duration is auto-calculated as max(time + duration + delay) across all entries — :add updates it on every insert.
• Loop behaviour: when _loops is 0 the timeline loops forever; on each loop boundary every contained tween's state is reset to pending so the loop replays from scratch. yoyo flips forward / reverse on each loop.
• All methods are chainable (return self) except update, the getters, and the state-mutating ones that need a clear return value.