What is a Timeline?

Timelines let you write 3D behaviors like a story using async generator functions. You yield actions, wait for conditions, and compose sequences, loops, and parallel flows in a readable way.

At a high level, timelines are composed of actions and sub‑timelines. You chain them sequentially or run them in parallel to build rich behaviors.

An action is a unit of work you yield* from a timeline. It can:

Use an action when you want to perform work over time, wait for something to happen, or both.

yield* action({
  update: (state, clock) => {
    // apply changes every frame
    return false // finish immediately
  },
})

yield* action({ until: timePassed(1, 'seconds') })

An action runs until either:

If both are provided, the action keeps updating until the until resolves.

The clock passed to update(state, clock) contains:

A timeline is an async generator that yields actions (and can yield other timelines). You can loop, wait, and branch—writing behavior like a story.

A reusable timeline is a function that returns a timeline so it can be started many times.

async function* reusableFadeIn() {
  yield* action({ until: timePassed(0.5, 'seconds') })
}

// later inside another timeline
yield* reusableFadeIn()

// React
useTimeline(() => reusableFadeIn(), [someDep])

// Vanilla
const update = start(reusableFadeIn)
// in your render loop
update(state, deltaSeconds)

You can chain actions/timelines sequentially or run them concurrently.

// Sequential
yield* action(A)
yield* action(B)

yield* parallel('all', A, B)
yield* parallel('race', A, B)

Timelines compose: you can yield* another reusable timeline anywhere. This keeps complex behaviors modular and readable.

// Reusable timeline
async function* someReusableTimeline() {
    yield* action({ until: timePassed(0.5, 'seconds') })
}

// Compose inside another timeline
yield* someReusableTimeline()

Model behaviors as named states and transitions. graph(initial, stateMap) drives the flow; useTimelineGraph is the React wrapper.

yield* graph('Idle', {
  Idle: {
    timeline: () => action({ update: ... }),
    transitionTo: { Run: { whenPromise: () => timePassed(1, "seconds") } }
  },
  Run: {/* ... */},
})

Explore full, runnable examples in the tutorials: