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/moveToanimateposition,fade/fadeToanimateopacity. 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 toposition. - Raw animators reach any numeric field by name:
Motion.tweenTo(dot, { radius: 110 }, "600 millis"). Usetween/tweenTofor fields without a semantic helper —radius,width,fontSize, a camera'sfocusDistance.
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.
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.