Entities
Instantiate shapes, structure them with children, and read or write their live data
An entity is a kind of thing a scene can contain — Circle, Rect,
Square, Ellipse, Line, Path, Text, Image, Group, Hud, and the
Camera. Scene.instantiate creates a live instance of one, named by its
tag:
const circle = yield* Scene.instantiate("Circle", {
position: Entity.vec3({ x: -600, y: 100 }),
radius: 60,
fillColor: Color.hex("#7f5af0"),
});Every field has a sensible default — position is the center of the frame,
opacity is 1, fills are white. Instances are also Effects that resolve to
themselves, which is what lets animators chain off them with .pipe.
Shared fields
Every paintable entity carries the same built-ins alongside its own fields:
position, rotation, and scale (all Vec3), opacity, and visible
(renderers skip an instance whose visible is false).
Geometry is relative to position. A Line's start/end and a
Path's commands are offsets from the entity's position, so animating
position translates the whole shape rigidly — no per-shape bookkeeping.
Rounded rectangles
Set cornerRadius on a Rect to round all four corners, then animate it
with Motion.tweenTo(rect, { cornerRadius: 30 }, "1 second"). The default
is 0. Rendering clamps the radius between zero and half the smaller
absolute dimension; stored values and tween targets stay unchanged.
The fill and outline follow the same contour, including stroke trim and dashes.
See From box to pill for an animated example.
Structure: one tree, defined by children
Instances form a single tree. A Group's children list is polymorphic:
- a bare
stringbecomes aText, - a not-yet-yielded
Scene.instantiate(...)is resolved in place, - an existing instance is adopted into the group.
Children live in the group's local coordinates, so one motion on the group
carries the subtree. An instance is born under the ambient parent (the root
by default); Scene.appendChild(parent, child) and Scene.removeChild move
it later — DOM semantics, append detaches from the current parent first.
There is no per-instance parent argument.
Reading and writing data
Instance state is live scene data:
Scene.data(instance)— read the current data.Scene.update(instance, (d) => ({ ...d, ...changes }))— rewrite it between frames, instantly (no animation).
Animators are the third way — they write the same data, spread over frames. That's the next page.
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";// One tree of instances, structured by children. A Group's children list is// polymorphic — a bare string becomes a Text, a not-yet-yielded instantiate// resolves in place, an existing instance is adopted — and the group's motion// carries the whole subtree.export const scene = Scene.make( "instance tree", function* () { // created up front, handed into the children list by value const badge = yield* Scene.instantiate("Circle", { position: Entity.vec3({ y: 120 }), radius: 36, fillColor: Color.hex("#2cb67d"), }); const card = yield* Scene.instantiate("Group", { position: Entity.vec3({ x: -450 }), children: [ // a bare string → a Text "effect-motion", // a nested instantiate, NOT yielded — the children list resolves it Scene.instantiate("Text", { position: Entity.vec3({ y: -80 }), text: "one tree, structured by children", fontSize: 40, fillColor: Color.hex("#94a3b8"), textAnchor: "middle", baseline: "middle", }), // an existing instance → reparented into this group badge, ], }); // one motion moves the whole subtree yield* card.pipe( Motion.moveTo({ x: 250 }, "1200 millis", "easeInOutCubic"), ); // instance data is live: update rewrites it between frames yield* Scene.update(badge, (d) => ({ ...d, fillColor: Color.hex("#ff8906"), })); yield* Motion.wait("400 millis"); // built-in props every entity carries; visible skips rendering yield* Scene.update(badge, (d) => ({ ...d, visible: false })); yield* Motion.wait("500 millis"); yield* Scene.update(badge, (d) => ({ ...d, visible: true })); yield* Motion.wait("800 millis"); }, { width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);Next: Animators.