Tween — property animation

tween animates any target property over time — colour, alpha, scale, rotation, a bare number — from where it is to where you want it, over a duration, through an easing curve. It is motion's closest sibling: motion tweens position along a path, tween does the same for everything else. A tween is data, runs in the background on the stage's tick, and is exactly deterministic. Set a value's destination and let it glide there.

Status: design. Not built yet.

What it is

Where motion moves a target through space along a path, tween moves a target's properties through their value range: fade an alpha to 0, grow a scale to 2×, shift a colour to red, ease a number to a new value. Motion is really "tween the position along a path," so pulling tween out as its own system means everything animatable shares one clock and one easing library — the stage's.

A tween is from → to, over a duration, shaped by an easing curve, applied to a target property in the stage's Advance phase. Like a path, it is data you set up and hand off; it runs itself.

The tween model

tween.to(sprite, { alpha = 0, scale = 2 }, { duration = 1.5, easing = "ease-out" })

• to / from — to animates a property to a value from wherever it is now; from animates from a value to its current one (an entrance). Several properties in one call move together on one clock.
• duration — in stage ticks (or seconds mapped to ticks); the whole family shares the timebase.
• easing — the same curve library as motion: linear, ease-in, ease-out, cubic-bezier(…).
• loop / yoyo — repeat, or bounce back and forth (a pulse).
• delay — wait before starting.

The value at any tick is from + (to − from) × eased(t), with t = elapsed / duration — a pure function of progress, so a tween is as deterministic as a path.

What's tweenable

Any numeric or interpolatable target property in the registry: position (x / y), scale, rotation, alpha, a colour (interpolated per channel), or a caller-named value. tween writes these in the Advance phase, exactly as motion writes position — so a target can be moving (motion) and fading (tween) at once, each system touching different properties of the same target, with no coordination between them.

Lifetime and composition

tween.to fires and returns — it runs on the tick, advanced each frame. Its lifetime mirrors motion:

• runs until it reaches its target value, or loops / yoyos if told to;
• per-target, per-property single — a new tween on a property replaces one already running on it (retarget a fade mid-fade and it glides to the new goal from where it is), while tweens on different properties of the same target run together;
• stop(target, prop?) cancels; running(target, prop?) queries.

Sequencing several tweens (this, then that, then wait) is the timeline's job, not tween's — tween does one from→to; timeline orchestrates many.

On the stage

tween is a stage sibling: it reads its own curves, writes target properties in Advance, references no other system, and inherits the determinism contract — the same tween on the same target from the same tick yields the same values, and composes deterministically with motion and collision because the stage fixes the phase order.

Clients

• AntBASIC — a friendly TWEEN verb is the front door: TWEEN sprite%, "alpha", 0, 1.5 (fade over 1.5s) — a thin wrapper over tween.to.
• Luau — require("tween"): to / from / stop / running for tools and apps.

Related

• motion — the position sibling · stage — the substrate both sit on · timeline — sequencing tweens (next)
• luau_tween — the Luau API · AntBASIC — the TWEEN front door