effect-motion
Learn

Animators

The base/To pattern, semantic vs raw animators, and both call forms

An animator is an Effect that changes one instance's data over a span of frames. They all follow one pattern and come in two layers.

The base/To pair

Every animator ships as a pair distinguished only by where the origin comes from:

  • Motion.moveTo(dot, { x: 600 }, "1 second") — To form: origin read from the instance's current value. This is the one you want most of the time.
  • Motion.move(dot, { x: -600 }, { x: 600 }, "1 second") — base form: origin stated explicitly. Partial origins are filled from the current value.

Semantic vs raw

  • Semantic animators name an intent: move/moveTo animate position, fade/fadeTo animate opacity. Prefer these — moving an entity moves it as one unit, because its geometry (a Line's endpoints, a Path's commands, a Group's subtree) is relative to position.
  • Raw animators reach any numeric field by name: Motion.tweenTo(dot, { radius: 110 }, "600 millis"). Use tween/tweenTo for fields without a semantic helper — radius, width, fontSize, a camera's focusDistance.

Applicability is checked at compile time: fading an entity with no opacity field (the camera, say) is a type error naming the missing field. Colors tween too — Motion.tweenTo(dot, { fillColor: Color.hex("#ff8906") }, ...) interpolates through Lab.

The escape hatch: drive

When fields must move together in a way independent tweens can't express — a circular orbit derives both x and y from one angle — Motion.drive runs a pure function once per frame with the eased progress:

yield* dot.pipe(
	Motion.drive("2 seconds", "linear", (t, data) => ({
		...data,
		position: Entity.vec3({
			x: Math.cos(t * 2 * Math.PI) * 300,
			y: Math.sin(t * 2 * Math.PI) * 300,
		}),
	})),
);

fn must be pure — (t, data) => data, nothing else — which is what keeps the scene reproducible. Several of the Examples are built on this one primitive.

Two call forms

Every animator is callable data-first or pipeable — the same function:

yield* Motion.moveTo(dot, { x: 600 }, "1 second", "easeInOutCubic");

yield* dot.pipe(
	Motion.moveTo({ x: 600 }, "1 second", "easeInOutCubic"),
	Motion.fadeTo(0, "400 millis"),
);

Animators resolve with their instance, so they chain: each step in the pipe starts when the previous one lands.

Waiting

Motion.wait("400 millis") is the do-nothing animator — it holds the scene for an exact number of frames.

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";// The three animator families on one subject: moveTo animates position from// wherever it currently is, tweenTo animates any numeric field by name, and// fadeTo animates opacity. The base form (move, without To) states its own// origin — the dot teleport-starts each pass from an explicit x.export const scene = Scene.make(	"animator pairs",	function* () {		const dot = yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -600, y: 60 }),			radius: 50,			fillColor: Color.hex("#7f5af0"),		});		const label = yield* Scene.instantiate("Text", {			position: Entity.vec3({ y: -200 }),			text: "moveTo — origin read from the instance",			fontSize: 44,			fillColor: Color.hex("#94a3b8"),			textAnchor: "middle",			baseline: "middle",		});		// To-form: origin is the current value		yield* dot.pipe(Motion.moveTo({ x: 600 }, "1 second", "easeInOutCubic"));		yield* Scene.update(label, (d) => ({			...d,			text: "move — origin stated explicitly",		}));		// base form: from {x: -600} regardless of where the dot is now		yield* dot.pipe(			Motion.move({ x: -600 }, { x: 600 }, "1 second", "easeInOutCubic"),		);		yield* Scene.update(label, (d) => ({			...d,			text: "tweenTo — any numeric field, by name",		}));		yield* dot.pipe(			Motion.tweenTo({ radius: 110 }, "600 millis", "easeOutBack"),		);		yield* dot.pipe(			Motion.tweenTo({ radius: 50 }, "600 millis", "easeInOutCubic"),		);		yield* Scene.update(label, (d) => ({ ...d, text: "fadeTo — opacity" }));		yield* dot.pipe(			Motion.fadeTo(0.15, "600 millis"),			Motion.fadeTo(1, "600 millis"),		);		yield* Motion.wait("500 millis");	},	{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },);

Durations and those easing names are the next page: Timing.

On this page