effect-motion
Learn

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 string becomes a Text,
  • 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.

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";// 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.

On this page