A paper-cutout animation engine built for AI agents. You describe a short film; an agent writes it as code, extends the engine when it needs something new, renders it offline and checks its own frames. Everything on screen and everything you hear is generated by code: no image models, no music models, no assets.

Clawd rolls a snowball that grows until it escapes down the hill, gets buried by a tree, and ends up as the head of a snowman. With sound. Made with Claude Opus 5.5 (medium effort).

Clawd blows a dandelion in a meadow, dives into a pond that turns out to be a sea, bounces off a jellyfish and walks a string of lights over the rooftops. With sound. Made with Claude Opus 5.5 (medium effort).

A cat walks a moonlit ridge, leaps to the next roof and startles a pigeon. Made with Claude Opus 5.5 (medium effort).

A moon jelly drifts toward the light; a curious fish circles it and leaves with a school. Made with Claude Opus 5.5 (medium effort).

A copper moth wakes a seed in an abandoned observatory. Made with GPT 6 Astra (light effort).

An elder and a child keep a fire alive across eras. Made with GPT 6 Astra (light effort).

examples/ also has A veces, cae (kite), a kid whose kite falls when the wind drops; Lluvia (rain), a woman running through a storm toward a bus stop; and Manos (hands), hands on a rock wall under a turning sky.

Most films were close to one-shot: the agent got a one-line brief and full creative freedom, and the human asked for a few small corrections (a sound too loud, a timing, a framing). They are in examples/; each can be rendered with pnpm render <name>.

• Engine vs content. src/ is a generic engine: paper rendering, bone rigs with springs, a deterministic physics world, cameras with parallax, choreography, weather and sound. A film is content on top of it — a set, a cast and a performance — so a 20-second short is a few hundred lines.
• Agents extend the engine. When a film needs a new behaviour (a snowball that grows as it rolls, footprints, flames, synthesized music), the agent adds it to src/ as a parameterised primitive with a test, and the next film can use it.
• Life at bone level. Motion comes from springs, strands and physics driven by intents (speed, look, reach, beats), not from keyframed positions. Sound comes from the same events: a footstep sounds where a foot lands.
• Deterministic and offline. Fixed timestep, seeded randomness. Videos are rendered frame by frame in headless Chromium and piped to ffmpeg, so they come out smooth however heavy a frame is.
• Agents check their own work. Probes print the state of the story, frame grabs and contact sheets show the picture, and a spectrogram with loudness numbers stands in for ears.

The recommended way is to create your own project from the template and let an agent drive it with the bundled skill:

npm create papermotion@latest my-films     # or: pnpm create papermotion my-films
cd my-films
pnpm install
npx playwright-core install chromium       # headless browser for rendering (you also need ffmpeg)
pnpm render hello                          # → out/hello.mp4 (a starter scene)

Then open the folder with your coding agent and ask for a film with the skill. In Claude Code:

/papermotion make a 10-second short about a paper boat caught in the rain

Other agents can use the same skill from .agents/skills/papermotion/, or be told: "Use the papermotion skill to make a 10-second short about a paper boat caught in the rain."

The skill teaches the workflow (pitch, beats, blocking, look, detail, sound), the API, art direction, the pitfalls we hit, and how to inspect the result. A one-line brief is enough; give the agent creative freedom, then ask for corrections after watching the render.

The new project gets its own copy of the engine, in the spirit of shadcn/ui: the agent can read it and change it, and adding primitives to the engine is how the best films here were made. A library in node_modules would take that away.

The template leaves the example films out on purpose. An agent that has read other shorts tends to reuse their characters, sets and story beats. Starting from an empty examples/ keeps each new film original. The engine's lessons still travel with it, in the skill and in docs/field-notes.md.

Engine updates don't flow into existing projects automatically. Diff your src/ against a newer template if you want them.

This repository is where the engine is developed, and it contains the example films. If you ask an agent to make a new film here, tell it not to open examples/ (the AGENTS.md asks the same), or it may borrow from them.

pnpm install
pnpm render snow        # offline render → out/snow.mp4 (any name in examples/catalog.ts, or: all)
pnpm dev                # http://localhost:5299/?example=snow plays out/snow.mp4; add &live to run it live
pnpm grab snow 1 4 7    # frames + probes at those seconds → out/grab/ (add --probe for numbers only)
pnpm sheet snow         # contact sheet of the rendered video
pnpm listen snow        # mix only the soundtrack (seconds): wav, spectrogram, loudness, cue list
pnpm test
pnpm typecheck
pnpm template           # build the project template → packages/create-papermotion/template

Rendering needs ffmpeg and a Chromium (npx playwright-core install chromium, or set CHROMIUM_PATH). The code runs on Node 22.18+ (TypeScript scripts run natively).

class Marea extends Stage {
  constructor(canvas: HTMLCanvasElement) {
    super(canvas, { duration: 10 });
    // build the world, cast and camera…
    this.beats = new Beats<'arrive' | 'inspect' | 'leave'>('arrive', {
      arrive:  { during: () => fish.steer(steer.arrive(fish.pos, jelly.center, 280)), next: () => near() && 'inspect' },
      inspect: { during: () => fish.steer(steer.orbit(fish.pos, jelly.center, 240, 200)), after: 1.4, then: 'leave' },
      leave:   { enter: () => { fish.kick({ x: 480, y: -90 }); this.cue('swish'); } },
    });
  }
  protected update(t: number, dt: number) { this.beats.update(t, dt); this.fish.update(dt); }   // before physics
  protected lateUpdate(t: number, dt: number) { this.cam.update(this.fish.pos.x, dt, t); }     // after physics
  protected draw(t: number) { /* camera layers, back to front */ }
  soundtrack(sampleRate: number) { /* voices, a score and a Mixer, from this.sound */ }
}

Sound is generated by code too. The simulation fires cues where things happen (this.cue('step', { gain, pan }) in a beat or on a contact) and records continuous levels (this.level('roll', speed)). Once the story has run, the stage's soundtrack(sampleRate) turns them into sound: voices and instruments built from the audio primitives, a score, a Mixer. Sounds are placed at videoTime(cue.at), so they stay in sync through slow motion, and can play at rateAt(cue.at) to slow down with the picture. A scene without a soundtrack stays silent.

pnpm render (scripts/render.ts) starts Vite, opens each scene headless in Chromium and pipes every frame to ffmpeg (H.264; libx264 if available, else libopenh264). It relies on what a mounted stage exposes on window: meta, frame(n) (JPEG data URL), probe(n), audio() (the mixed soundtrack as a WAV, plus the cues), reset() and ready. ?example=<name>&headless mounts a stage paused, waiting for frames to be pulled; frames must be requested in increasing order. When a scene has a soundtrack, the render muxes it into the MP4 and writes out/<name>.wav and out/<name>_audio.png.

MIT