Getting started
Install effect-motion, write a first scene, play it, and export a frame
The fastest path is the project scaffolder — it sets up TypeScript, the studio previewer, and a render entrypoint in one step:
bun create effect-motionThen motion studio previews your scenes with hot reload, and
motion render writes MP4s. The rest of this page does the same thing by
hand, so you can see every part.
Install
bun add effect-motion @effect-motion/react effecteffect is pinned exactly by the scaffolder on purpose: the seed-derived
random sequences are a determinism invariant, so effect-motion and effect
upgrade together, deliberately.
Write a scene
A scene is a program: instantiate entities, then animate them. Coordinates are
center-origin and y-up — { x: 0, y: 0 } is the middle of the frame, and
positive y is toward the top.
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";
export const scene = Scene.make(
"my first scene",
function* () {
const circle = yield* Scene.instantiate("Circle", {
position: Entity.vec3({ x: -600 }),
radius: 60,
fillColor: Color.hex("#7f5af0"),
});
yield* circle.pipe(
Motion.moveTo({ x: 600 }, "1 second", "easeInOutCubic"),
);
},
{ width: 1920, height: 1080, backgroundColor: Color.rgba(22, 22, 29) },
);Scene.instantiate creates a live instance within the current frame — no
time passes — and Motion.moveTo animates its position over exactly one
second of frames. Time advances only when an animator (or an explicit hold)
closes frames.
Play it
The <Player> component from @effect-motion/react runs the scene in the
browser with transport controls — play/pause and a scrubbable progress bar:
import { Player } from "@effect-motion/react";
import { scene } from "./my-scene";
export function App() {
return <Player scene={scene} autoPlay />;
}The Player sizes itself from the scene's own resolution; frames stream in as the scene runs, so playback starts before the whole scene is computed.
Export it
@effect-motion/export turns the same frames into an MP4 — the bundled ffmpeg
means no system install:
import { NodeServices } from "@effect/platform-node";
import { Video } from "@effect-motion/export";
import * as Effect from "effect/Effect";
import { scene } from "./my-scene";
Video.render(scene, "./out.mp4").pipe(
Effect.provide(NodeServices.layer),
Effect.runPromise,
);Run it with tsx render.ts. What the Player showed is what the file contains —
both consume the same frame stream through the same renderer.
Next
Work through Learn in order — each page covers one primitive and ends with a complete scene using it.