Class: BuildStage<S>

Defined in: render/build-stage.ts:18

The determinism + scene-binding machinery a Scene runs its generator against. One BuildStage is created per build pass and re-bound to each scene in turn (see bindScene); the scene-authoring surface (add/set/ sounds/to/camera/paint commands) is supplied by the bound Scene itself, and the precise author-facing type is the Stage alias in @/nodes (a BuildStage merged with the scene's authoring methods).

@/render must not import @/nodes (that would be circular), so BuildStage is generic over its bound scene type S rather than importing Scene. The runtime constructs new BuildStage<Scene>(...); the S flows back out via scene so the merged Stage type stays fully typed.

Type Parameters

S

S = unknown

Constructors

Constructor

new BuildStage<S>(viewport, fps): BuildStage<S>

Defined in: render/build-stage.ts:28

Parameters

viewport

Size2D

fps

number

Returns

BuildStage<S>

Properties

fps

readonly fps: number

Defined in: render/build-stage.ts:23

Target frames-per-second of the composition.

viewport

readonly viewport: Size2D

Defined in: render/build-stage.ts:20

Canvas dimensions in pixels.

Accessors

scene

Get Signature

get protected scene(): S

Defined in: render/build-stage.ts:73

The scene currently bound to this stage. The author-facing Stage type merges the bound scene's authoring methods onto the stage, so generators call stage.add(...)/stage.zoomTo(...) directly; internally those resolve through here.

Returns

S

Methods

bindScene()

bindScene(scene): void

Defined in: render/build-stage.ts:63

Bind the scene whose generator is about to run, so its authoring methods are reachable for the duration of the build. The runtime calls this before driving each scene's generator; one stage is reused across all scenes in a pass, re-bound per scene.

Parameters

scene

S | null

Returns

void

random()

random(seed?): Random

Defined in: render/build-stage.ts:101

Get a seeded Random source for this build.

const random = stage.random("sparkle"); const xs = random.floatArray(40, -100, 100); const drift = random.noise(t, 6);

The seed lives on the returned source, not on the stage, so determinism is scoped per source: several random(...) calls with distinct seeds give independent reproducible streams. A string seed is djb2-hashed; omit the seed to get the fixed default 0 (matching Node.random), so an unseeded source is stable rather than time-varying — the stage keeps no seed of its own.

Sources are cached by seed for the life of the stage and rewound by reset before each timeline replay — so a scene that re-runs its generator (scrub, precomp, HMR) draws the identical sequence every pass, whether or not it named a seed.

Parameters

seed?

string | number

Returns

Random

reset()

reset(): void

Defined in: render/build-stage.ts:123

Rewind all stateful generators so the next replay is identical to the first. Called by the runtime before each scene.build(...).

Each cached Random is reset to its seed (rather than dropped) so a generator that re-calls random(seed) on replay gets back the same source at the head of its sequence — preserving determinism even for the unseeded default source.

Returns

void

variables()

variables<T>(key, fallback?): T | undefined

Defined in: render/build-stage.ts:50

Read a project variable by its (flat) name, e.g.

Variables are the project's variables map (registered globally before the build) — arbitrary constants like corner radii, durations, counts, or flags that, unlike colors and typography, have no string-resolution channel of their own. The type parameter asserts the expected value type and defaults to number (the common case); it is an unchecked assertion of whatever the project declared, not validation. Lookup is case-insensitive.

Returns fallback when the variable is absent, or undefined when no fallback is given — so an author can stage.variables('x') ?? default too.

Type Parameters

T

T = number

Parameters

key

string

fallback?

T

Returns

T | undefined