effect-motion
Learn

Scenes

A scene is an Effect that produces frames — Scene.make, Settings, and the frame model

A scene is an Effect: a program that, when run, produces an exact sequence of frames. You author it with Scene.make, giving it a name, a generator body, and its settings:

export const scene = Scene.make(
	"hello scene",
	function* () {
		// instantiate entities, animate them — each yield* is one step
	},
	{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },
);

The generator syntax is how Effect programs compose: every yield* runs another Effect inside the scene. Crucially, yielding is not what makes time pass — instantiating an entity, reading data, or drawing a random number all happen within the current frame. Time advances only when something closes frames: an animator, a hold, or the frame barrier itself.

Settings

The settings object fixes everything a run depends on:

  • width / height — the frame size in scene units. Coordinates are center-origin, y-up: { x: 0, y: 0 } is the middle, y: 540 the top edge of a 1080-tall scene.
  • frameRate — frames per second (default 60).
  • backgroundColor — the frame clear color.
  • seed — the string every random value derives from (default "effect-motion"). See Randomness.
  • maxFrames — a runaway guard (default 36 000 frames). Set Infinity to declare an intentionally infinite scene.

Frames, exactly

A scene doesn't play in wall-clock time — it produces frames, one tick at a time. "1 second" at 60 fps is exactly 60 frames, the last of which lands exactly on the animation's target. Concurrent animations advance through a shared frame barrier, so no interleaving ever changes the output. This is what makes scenes deterministic: same settings, same seed, same frames — every run, every machine.

Two ways to consume a scene directly (the Player and export do this for you):

  • Scene.run(scene) — collect the full frame list.
  • Scene.stream(scene) — pull frames lazily as they're produced.

Making time pass

Three ways frames get produced, from highest level to lowest:

  • Animators — Motion.moveTo(dot, ..., "1 second") closes exactly one second of frames while it interpolates.
  • Holds — Scene.sleep("600 millis") closes that many frames with nothing moving (Motion.wait is the same hold, shaped for use inside an animator chain).
  • Scene.tick — close exactly one frame, manually. The primitive the other two are built on; reach for it when you're driving per-frame logic yourself.
0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Motion from "effect-motion/Motion";import * as Scene from "effect-motion/Scene";// A scene is a program. Instantiating is instant — no frames pass — and// time advances only when something closes frames: an animator, a wait,// or a bare Scene.tick. The timeline still reads top to bottom.export const scene = Scene.make(	"hello scene",	function* () {		const title = yield* Scene.instantiate("Text", {			text: "a scene is a program",			fontSize: 96,			fillColor: Color.hex("#fffffe"),			textAnchor: "middle",			baseline: "middle",			opacity: 0,		});		yield* title.pipe(Motion.fadeTo(1, "800 millis"));		yield* Motion.wait("600 millis");		// moving up is one more statement — scene time flows with the code		yield* title.pipe(Motion.moveTo({ y: 90 }, "700 millis", "easeInOutCubic"));		const sub = yield* Scene.instantiate("Text", {			position: Entity.vec3({ y: -60 }),			text: "time advances only when something animates",			fontSize: 48,			fillColor: Color.hex("#94a3b8"),			textAnchor: "middle",			baseline: "middle",			opacity: 0,		});		yield* sub.pipe(Motion.fadeTo(1, "800 millis"));		yield* Motion.wait("1 second");	},	{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);

Next: Entities — what those instantiated things are.

On this page