core

Core tween object — lifecycle, interpolation, chaining, controls, entity integration. Owned by the parent tween module; user code should require @builtin::modules.tween and use its re-exports (tween.to, tween.fromTo, tween.create, tween.update, etc.) rather than going through this submodule directly.

Exports

Tween lifecycle:

• Core.to(entityId, property, target, durationOrOpts, easing?) -> Tween — auto-started property tween.
• Core.fromTo(fromVal, toVal, durationOrOpts, easing?) -> Tween — auto-started raw value tween.
• Core.create(opts: TweenOpts) -> Tween — pending tween (no auto-start).
• Core.update(dt: number) — advance all active tweens; honours setGlobalSpeed.

Global controls:

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

Exposed internals (for the Timeline submodule):

• Core.Tween — the Tween class. Use Tween:start, :pause, :resume, :cancel, :reverse, :andThen, :with, :getState, :getValue, :getProgress.
• Core.ENTITY_PROPS — the accessor map for entity-bound properties.

Types:

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

Usage

-- Prefer the public surface:
local tween = require("@builtin::modules.tween")
tween.to(id, "position", target, 1.0, "easeOutQuad")

Notes

• A Tween instance carries _id, _state, _elapsed, _duration, _delay, _easingFn, _loops, _yoyo, callback fields, and chain links (_next, _parallel). Treat these as opaque from user code.
• Entity-bound tweens lazily resolve the from value at :start() (or after the delay window closes) so the entity's current value is captured at the right moment. Direct from in opts overrides this.
• An entity-bound tween auto-cancels when the target's property accessor returns nil (entity despawned mid-tween).
• Supported property types: number, vec3 { x, y, z }, color { r, g, b, a? }. The lerp function is picked from the from value's shape.
• Tween:andThen chains sequentially; Tween:with runs another tween in parallel. Chains walk to the tail so multiple andThen calls link end-to-end.
• Internal helpers (lerpNumber, lerpVec3, lerpColor, pickLerp, cloneValue, Tween.new, every Tween:* method) stay un-typed per the spec — they're not part of the public surface.