PaperMotion

Code-driven paper-cutout animation engine with bone rigs, Verlet physics, parallax sets, choreography beats, and offline MP4 rendering.

By francozanardi @francozanardi Verified Mirror Raw SKILL.md
Install PaperMotion
npx lumoz-skills add papermotion

Adds SKILL.md and references to .agents/skills/papermotion/.

https://lumozai.com/api/mcp

Connect Lumoz MCP once in Claude to get PaperMotion and every LumozAI skill automatically (lumoz_get_skill("papermotion")). Setup guide →

git clone https://github.com/LumozAI-com/papermotion .agents/skills/papermotion

Clones the pinned, NVIDIA SkillSpector-verified mirror with all scripts and references.

Category
Media & Motion
Security
NVIDIA SkillSpector Passed
License
MIT (Free)
Compatible Runtimes
Antigravity, Claude Code, Cursor, Windsurf

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 to know what exists. Don't reinvent a primitive the engine has.
  3. 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 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.
  • 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.
  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.

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.

Frequently asked questions about PaperMotion

What does the PaperMotion AI agent skill do?

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.

How do I install PaperMotion in Claude Code, Cursor, or Antigravity?

Run `npx lumoz-skills add papermotion` in your project root, or clone https://github.com/LumozAI-com/papermotion into `.agents/skills/papermotion`. Compatible runtimes (Antigravity, Claude Code, Cursor, Windsurf) discover `.agents/skills/papermotion/SKILL.md` automatically.

Is PaperMotion verified and safe to run?

Yes. PaperMotion passed NVIDIA SkillSpector security inspection with 0 critical or high findings and is pinned to immutable commit 9ce8490 under LumozAI-com.

Can AI agents fetch PaperMotion automatically via MCP or REST API?

Yes. Agents connected to Lumoz MCP can call lumoz_get_skill("papermotion"), or any pipeline can fetch raw Markdown from https://lumozai.com/api/skills/papermotion/raw.