effect-motion
Guides

Extend the vocabulary

Userland builders, nested scenes, and custom render implementations

The entity union is deliberately closed — Circle, Rect, Path, Text, and friends are the complete set the engine steps and animators type-check against. Extending the vocabulary happens at three levels, none of which touch the engine.

Userland builders

The engine renders, it does not parse: anything that composes existing entities belongs in a plain function. A "component" is a function that returns instances:

const labeledDot = (label: string, x: number, y: number, hex: string) =>
	Scene.instantiate("Group", {
		position: Entity.vec3({ x, y }),
		children: [
			Scene.instantiate("Circle", {
				radius: 40,
				fillColor: Color.hex(hex),
			}),
			Scene.instantiate("Text", {
				position: Entity.vec3({ y: -80 }),
				text: label,
				fontSize: 36,
				fillColor: Color.hex("#94a3b8"),
				textAnchor: "middle",
			}),
		],
	});

const p0 = yield* labeledDot("P0", -600, 200, "#7f5af0");

Expensive preprocessing (parsing markdown into text runs, sampling data files) runs before Scene.make, memoized in userland — frames may be computed during playback, so the per-frame path should only render.

Nested scenes

A scene is a plain value, and a movie is a scene that plays other scenes. Scene.play(scene) runs one as a branch — sharing the movie's runner, frame rate, and frame cap — and returns a handle whose finished you can await. The played scene keeps its own camera and clips to its own bounds (Precomps, masks and HUD). Combined with Scene.finish (which lets a scene end while a tail keeps animating), transitions stay in the movie's hands:

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 movie is a scene that plays other scenes. Scene A declares itself// finished when its crossing is done — the fade-out afterwards is a TAIL:// it keeps playing, but nothing waits for it, so B's entrance overlaps it.const sceneA = Scene.make(	"scene A",	function* () {		const c = yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -700, y: 140 }),			radius: 60,			fillColor: Color.hex("#e53170"),		});		yield* Motion.moveTo(c, { x: 700 }, "1 second", "easeInOutCubic");		yield* Scene.finish;		yield* Motion.fadeTo(c, 0, "1 second");	},	{ width: 1920, height: 1080 },);const sceneB = Scene.make(	"scene B",	function* () {		const c = yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -700, y: -140 }),			radius: 60,			fillColor: Color.hex("#2cb67d"),		});		yield* Motion.fade(c, 0, 1, "600 millis");		yield* Motion.moveTo(c, { x: 700 }, "1 second", "easeInOutCubic");	},	{ width: 1920, height: 1080 },);// the movie owns the transition: B starts the moment A FINISHES, while A's// fade-out tail keeps playing over B's entranceexport const scene = Scene.make(	"crossfade",	function* () {		const a = yield* Scene.play(sceneA);		yield* a.finished;		const b = yield* Scene.play(sceneB);		yield* b.finished;	},	{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);

Custom render implementations

Rendering is the renderer package's job, and its registry is open: each entity kind has a retained implementation with three moments —

  • build — create the three.js object when the instance first appears,
  • update — mutate it when data or world position changed (skipped entirely on frames where nothing did),
  • dispose — release GPU resources when the instance leaves.

Pass your own through the renderers option on Renderer.make (or the Node adapter's make); the map merges over the built-ins by entity tag, so the same mechanism overrides how an existing kind draws. The docs player wires only the built-ins, which is why this page shows no live example — wire yours in your own app's renderer.

On this page