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:
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.