Papermotion

---
name: papermotion
description: Make short animated films in the papermotion paper-cutout engine: everything generated by code (no image models or assets), characters rigged with bones, springs and strands, physics, parallax sets, choreography with beats, multi-shot edits, weather and film finishing, rendered offline to MP4. Use when asked to create, extend or polish a papermotion scene, short, story, demo, character, set or camera work, or to add engine features for one.
compatibility: Needs Node with pnpm, ffmpeg, and a Chromium for playwright-core (npx playwright install chromium, or CHROMIUM_PATH).
metadata:
  project: papermotion
  version: "1.0"
---

# papermotion

papermotion is a TypeScript engine that makes short films out of **cut paper**:
- torn edges that boil, fiber texture and drop shadows;
- rim light and core shadow;
- characters built from bones with springs, and strands for hair and tails;
- a deterministic Verlet physics world;
- parallax camera layers, choreography, weather and film finishing.

You write a scene as code, render it offline and look at the frames. The engine lives in `src/`, and
scenes import only from its public index (`src/index.ts`).

A good papermotion short:
- has a clear little story;
- has original characters and sets, each a cohesive piece of paper with detail where the camera is
  close;
- moves with physics that reads right in a paper world;
- is shot with intention: framing, cuts, moves.

## Before you start

1. Read `AGENTS.md` and `README.md` at the repo root (conventions, commands).
2. Skim [references/engine-api.md](references/engine-api.md) to know what exists. Don't reinvent a
   primitive the engine has.
3. Read [references/pitfalls.md](references/pitfalls.md). Every item there cost hours once.

Load the other references when you reach that part of the work:

| You are… | Read |
| --- | --- |
| Structuring the scene, beats, shots, cameras, transitions | [references/scenes.md](references/scenes.md) |
| Building a character or creature | [references/characters.md](references/characters.md) |
| Designing sets, light, color, composition, close-ups | [references/art-direction.md](references/art-direction.md) |
| Checking your work (probes, frame grabs, renders) | [references/inspection.md](references/inspection.md) |
| Adding sound effects, ambience or music | [references/sound.md](references/sound.md) |

## Principles

- **Generated by code.** No image files, no image models. Everything is a polygon, a strand or a
  gradient drawn with `Paper`.
- **Engine vs content.** A new reusable behaviour goes in `src/` as a generic, parameterized primitive,
  with a test and an export in `src/index.ts`. Examples: a way to move, a contact, a paper effect, a
  camera or edit tool. Story-specific content (this cat, this bus, this house) stays in the scene
  folder. Don't grow a catalog of props in the engine.
- **Original work.** Invent the cast, sets and story for each new short. Reuse engine primitives
  freely, but not another short's characters or props.
- **Life at bone level.** Motion comes from intents (speed, look, reach, crouch) driving springs, gaits,
  strands and physics. It never comes from keyframing positions. Use `keys()` only to shape an intent
  over time.
- **Acceptable within the universe.** Physics should read right for paper, not be realistic. Snappier
  jump gravity, soft collisions and stylized drag are fine.
- **Deterministic.** Fixed timestep, seeded `rng`/`hash`/`noise1`. Never use `Math.random` or wall-clock
  time. Frames render in increasing order only.
- **Offline rendering.** Judge motion only from the rendered MP4 (`pnpm render`), never from the live
  browser view.

## Workflow

Follow this loop. Iterating on numbers and single frames is cheap; full renders take minutes.

### 1. Pitch and plan (before code)

- Write a one-paragraph story with a beginning, a turn and an ending. Keep it to 10–30 s.
- **Make it different** from the obvious. Ask what the engine has not shown yet. Prefer one clear
  action over subtle symbols: viewers didn't read a lost shoe or an unravelling scarf as metaphors.
- List the **beats** of each actor (what they do, what ends each beat) and the **shots**
  (framing, zoom, when to cut).
- List the **interactions with the environment**. They make a short feel alive: grass bending,
  something bouncing, a splash, a wire that sags, seeds blown away.
- Decide what is **engine** (new primitive) and what is **content**.

### 2. Scaffold

- Create `examples/<name>/main.ts` with a class extending `Stage`, and register it in
  `examples/catalog.ts`. Put characters and props in files next to it.
- The minimal shape is in [references/scenes.md](references/scenes.md#anatomy-of-a-scene).
- Add a `probe()` from the start. Include positions, the current beat and shot, and the beat history.

### 3. Build in passes

1. **Blocking.** Place the set and the actors as simple shapes, get the beats and timing right, and
   verify them with probes.
2. **Motion.** Gaits, jumps, contacts, physics props, cameras and cuts.
3. **Look.** Paper sheets, tones, light direction, layers, atmosphere.
4. **Detail pass** on anything close to camera: eyes, faces, markings, texture of masses. See the
   checklist in [references/characters.md](references/characters.md#detail-pass).
5. **Finishing.** Grade, grain, vignette, letterbox, transitions, titles.
6. **Sound.** Cues and levels from the simulation, then a `soundtrack` with effects, ambience and a
   score. See [references/sound.md](references/sound.md).

### 4. Inspect, fix, repeat

```bash
pnpm grab <name> 1 3.5 6 9 --probe   # numbers only: beats, positions (seconds, increasing)
pnpm grab <name> 1 3.5 6 9           # frames → out/grab/<name>_<t>.jpg + a contact sheet
pnpm render <name>                   # full offline render → out/<name>.mp4
pnpm render <name> --draft           # half resolution, ~3× faster → out/<name>_draft.mp4
pnpm sheet <name> 2 0 10             # contact sheet of the video (fps, from, seconds)
pnpm listen <name>                   # soundtrack only (seconds): wav, spectrogram, loudness, cue list
pnpm typecheck && pnpm test
```

- Look at the images you grab.
- **Check at full resolution**: proportions, seams, faces, silhouettes.
- **Check the video** for timing and smoothness.
- Don't declare something done until you have seen it.
- See [references/inspection.md](references/inspection.md).

### 5. Report honestly

Say what works and what still looks weak. Keep notes for next time in `docs/field-notes.md`: the
mistake, the fix, and why it worked.

## Quality bar (check before you call it done)

- [ ] The story reads without text. The key moment happens in frame, big enough, and clearly staged.
- [ ] Each character is **one piece of paper** (`paper.sheet`). Limbs don't read as separate parts,
      and markings stay inside the silhouette (`paper.inside`, `paper.clip`).
- [ ] Nothing near the camera is a flat color: it has a core shadow, a rim light and at least two tones.
- [ ] Eyes have life: an iris or shape, a catchlight, lids or blinks, and a look direction.
- [ ] There is one light direction per shot (`paper.light`), and rim and shade agree with it.
- [ ] Layers separate by value: far layers take on the color of the air.
- [ ] Parallax works: far layers move slower, and props on them are placed with `cam.toLayer`.
- [ ] Nothing pops. Strands and props don't jump between frames, and cameras have no violent first
      frames.
- [ ] Contacts are real: feet on the floor, bodies touching what they touch, no floating props.
- [ ] Cuts happen on action. Close-ups keep line weights thin (scale rim, shade and lines by zoom).
- [ ] Deterministic: the same frame renders the same image twice. Typecheck and tests pass.