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
- Read
AGENTS.mdandREADME.mdat the repo root (conventions, commands). - Skim references/engine-api.md to know what exists. Don't reinvent a primitive the engine has.
- Read 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 |
| Building a character or creature | references/characters.md |
| Designing sets, light, color, composition, close-ups | references/art-direction.md |
| Checking your work (probes, frame grabs, renders) | references/inspection.md |
| Adding sound effects, ambience or music | 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 insrc/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 useMath.randomor 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.tswith a class extendingStage, and register it inexamples/catalog.ts. Put characters and props in files next to it. - The minimal shape is in references/scenes.md.
- Add a
probe()from the start. Include positions, the current beat and shot, and the beat history.
3. Build in passes
- Blocking. Place the set and the actors as simple shapes, get the beats and timing right, and verify them with probes.
- Motion. Gaits, jumps, contacts, physics props, cameras and cuts.
- Look. Paper sheets, tones, light direction, layers, atmosphere.
- Detail pass on anything close to camera: eyes, faces, markings, texture of masses. See the checklist in references/characters.md.
- Finishing. Grade, grain, vignette, letterbox, transitions, titles.
- Sound. Cues and levels from the simulation, then a
soundtrackwith effects, ambience and a score. See references/sound.md.
4. Inspect, fix, repeat
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 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.
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.