Timeline — sequencing

timeline orchestrates the other systems over time: play these together, then that, wait, loop, jump. Where motion and tween each do one thing, timeline arranges many into an authored whole — a cutscene, an attack pattern, a UI transition. A timeline is data, scheduled on the stage tick, deterministic, and seekable. It writes no target state itself; it fires the siblings at the right ticks.

Status: design. Not built yet.

What it is

motion glides a sprite along a path; tween fades its alpha; each is one action. A real animation is many actions arranged — move and fade together, then wait, then flash, then loop. timeline is that arranger: a schedule of steps, each starting a sibling's sequence (or a wait, or a call), placed in time so the whole plays as one authored piece.

It is an orchestrator, not a mover — it never writes x / y / alpha; it starts motion / tween at scheduled ticks and lets them do the writing. So it composes with everything already on the stage for free.

The model — parallel and sequential

Parallel and sequential actions

A timeline is built from two relationships and a few leaf steps:

sequential — a step after the previous finishes (then);
parallel — a step alongside the previous (with);
wait d — a gap;
call fn — fire a handler or event at a point;
and timelines nest — a timeline is itself a step, so complex arrangements stay readable.

timeline.new()
  :add(  motion.play(hero, walk$) )          -- start walking
  :with( tween.to(hero, { scale = 1.2 }) )   -- ...and grow, at the same time
  :wait( 0.5 )
  :then_( tween.to(hero, { alpha = 0 }) )    -- then fade out
  :call( function() emit("hero:gone") end )
  :play{ loop = false }

Under the friendly builder it is just data — a list of { at, action } scheduled by tick — so a timeline can equally be authored as a table, saved, or generated.

Scheduled on the tick — and seekable

play advances the schedule on the stage tick: each step fires when its start tick arrives. Because every action underneath is a deterministic function of progress, the timeline gets a property most animation systems don't get cheaply:

seek(t) — jump to any time and the whole arrangement is computed to exactly its state at t — scrub a cutscene, preview a frame, step a test. Deterministic, because there is no hidden accumulated state, only functions of t.
play / pause / stop, loop, and a timeline speed (its whole rate, over the siblings' own).

On the stage

timeline is a stage sibling that drives other siblings: it reads its own schedule, starts and stops motion and tween sequences at scheduled ticks, writes no target state directly, and inherits the determinism contract — the same timeline from the same start tick produces the same show every time, and seek(t) lands on exactly the frame play would.

Clients

Luau — require("timeline"): build, then play / seek / stop, for cutscenes, UI choreography, attack patterns.
AntBASIC — the friendly slice is sequential: a SCENE … END SCENE block, or chaining DRAW / TWEEN with THEN / WAIT, over timeline.