Papermotion: make a paper-cutout short you can inspect and revise

What the documentation establishes

The documented template workflow renders a starter scene to out/hello.mp4 and requires Node 22.18+, ffmpeg and Chromium. Source ↗

A created project contains its own engine copy; upstream engine changes do not automatically update existing projects. Source ↗

The repository package file declares version 0.1.0 and pnpm 11.1.3, with render, grab, sheet, test and typecheck scripts. Source ↗

The walkthrough below is an original worked exercise. We have not independently tested this product’s performance.

1. Establish a working starter before asking for a film

Use a new empty working directory. The commands below create a folder named my-films; run later commands inside that folder. Check your prerequisites first. If a command is missing, install that prerequisite through its official installation instructions before continuing. This guide assumes you already have Node, npm, pnpm and ffmpeg; it is not an operating-system installation guide.

node --version
npm --version
pnpm --version
ffmpeg -version

npm create papermotion@latest my-films
cd my-films
pnpm install
npx playwright-core install chromium
pnpm render hello

Open out/hello.mp4 in a video player. Do not proceed if it is absent or cannot play: a story prompt cannot fix a missing browser or encoder. Save the generated package.json and lockfile with the project. Because @latest moves, record the creation date and dependency versions so a later problem can be compared with the same starting point. A repository version and a downloaded template may differ; inspect the actual generated files.

2. Give the agent a complete, bounded story

Our input is a fictional twelve-second film called Seed Delivery. A paper beetle carries a blue seed from the left of the frame to an empty orange pot on the right. The obstacle is a small gap, not an enemy or a new scene. A clear beginning, obstacle and visible finish makes this easier to assess than a request for something cinematic. No source footage, music or character assets are needed.

Open my-films in your coding agent. Paste this complete brief and ask it to use the bundled papermotion skill. A skill is a file containing task instructions and references; its presence does not itself start an agent. If your client does not discover it, explicitly point it to .agents/skills/papermotion/SKILL.md.

Use the bundled papermotion skill in this project.
Create a new scene named seed-delivery. Work inside this project only.
Output: a silent, 12-second, 1280x720 paper-cutout animation.
Story: a small beetle carries one blue seed to an orange pot.
0–3 seconds: show beetle and seed at left; empty pot visible at right.
3–6 seconds: beetle approaches a narrow gap and pauses.
6–9 seconds: beetle crosses the gap while keeping hold of the seed.
9–12 seconds: seed enters pot; beetle stops beside it; hold the finish.
No subtitles, title cards, music, logos, imported assets or other characters.
Use fixed simulation time and seeded randomness. Do not use wall-clock time.
Read the installed engine API before writing code. Add the scene under
examples/seed-delivery/ and register seed-delivery in examples/catalog.ts.
Preserve the hello scene. Do not replace the engine with an unrelated library.
First create blocking with simple shapes; then improve paper texture and motion.
Add probe output for beat, seed location, beetle location and delivery status.
Run typecheck and tests. Render a draft, inspect frames at 1, 4, 7, 10 and 11.5
seconds, then report which requirements failed. Fix those before the final MP4.
Do not publish or upload the result. If an installed API differs from your
references, report the exact missing export and adapt to the local API.

3. Approve the story before polishing the illustration

Have the agent show its beat plan and first draft. Here, blocking means the rough placement and timing of simple shapes. Judge whether you can follow the seed without reading an explanation. Do not add detailed backgrounds while the important action is out of frame. The finish must be visible in the film, not merely asserted in a chat reply.

The probe is a small report from the simulated scene. Ask for the fields named in the brief so you can distinguish a missing event from an unclear picture. A delivery flag becoming true does not prove that the seed visibly entered the pot; use both the report and the images.

pnpm typecheck
pnpm test
pnpm grab seed-delivery 1 4 7 10 11.5 --probe
pnpm render seed-delivery --draft
pnpm grab seed-delivery 1 4 7 10 11.5

Expected files include out/seed-delivery_draft.mp4 and frame images under out/grab/. Open them. If the scene name is unknown, check the catalog registration before changing the render command. Grab times must increase. Record the actual console error if rendering fails rather than accepting the agent’s description of what it intended to make.

4. Use explicit pass and fail criteria

Ask a person who has not read the brief to describe what happened in one sentence. If they cannot identify the delivery, improve staging rather than explaining the symbolism. This is an editorial acceptance check, not a benchmark of the underlying model. Save failures before fixing them so you can see whether a revision actually helped.

At second 7 the seed disappears behind the beetle. Keep the story, duration,
colors and camera framing unchanged. Adjust only seed placement/draw order
so it stays visible during the crossing. Re-run the probe and frame grabs
at 6, 7, 8 and 10 seconds. Show the changed files and any remaining failure.

5. Render the final and keep a reproducible handoff

pnpm typecheck
pnpm test
pnpm render seed-delivery
pnpm sheet seed-delivery 2 0 12

The intended final is out/seed-delivery.mp4. The sheet command samples the rendered video at two frames per second from zero through the twelve-second interval. Watch the MP4 itself for timing; a grid of stills cannot establish smooth motion. Check its duration and dimensions in your player’s media information. Keep the source, dependency lockfile, brief, final film and review note together.

This exercise is silent on purpose. An absent audio track is a pass here. Adding music later is a separate change with its own listening check. Record agent/model, date, tool versions, failed checks and correction time. Do not claim another person can reproduce identical AI-written source merely by using the same prompt; the saved source and environment are the reproducible artifact.

Film: seed-delivery
Checked source revision / template creation date:
Node / pnpm / ffmpeg versions:
Agent and model:
Output file, measured duration and dimensions:
Frames inspected: 1, 4, 7, 10, 11.5 seconds
Opening / obstacle / crossing / finish: PASS or FAIL, with reason
Full MP4 watched: YES or NO
Tests and typecheck: command result, not an inferred pass
Remaining defects:
Time spent correcting:
Permission to publish: not part of this exercise

6. Recover from common failures and plan maintenance

Rendering consumes local CPU time, disk space and energy; agent calls may consume plan quota or API credits. No measured runtime or cost is established here. The MIT repository is available publicly, but its experimental status means a finished-looking demo is not a compatibility guarantee. Use a small story to find the cost of iteration before committing to a long production.

The engine is copied into your project, so maintenance is deliberate. When a new template version appears, create a separate comparison copy, preserve this film and rerun the same frame checks. Record what changed and whether it improved the output. This turns an attractive experiment into a workflow whose limitations you can actually see.

Guide history

Revisions preserve the original instructions. A source recheck alone does not create a new revision.

Revision 1 · New documented creative workflow: complete original 12-second story brief, setup, exact inspection/render commands, pass/fail criteria, recovery and explicit unexecuted status.

Continue learning