claude-animation
Frame-exact, hand-drawn-looking 2D animation written as code. A film is a pure function
frame(ctx, t); the library draws the look (brush, pencil, watercolour, grain, hatching), the rigs act
(a detailed ant, a bean-bodied cast), and the harness renders, previews and checks it.
Every rule below is something that went wrong on a real film — a 59 s brush-ink + watercolour history recap and a set of storybook insect films — and took a render to find.
Read first
| I need to… | Go to |
|---|---|
| Make an original animation from a brief | references/workflow.md → templates/beat-sheet.md → templates/film-template.mjs |
| Make it more detailed (materials, textures, characters) | references/detail.md — the detail bible. Read it before drawing any surface |
| Draw / pose / walk the ant, or build a new creature rig | references/characters.md, lib/rigs/ant.mjs |
| A colony: leaves, brood, fungus, roots, a nest cross-section with walkable tunnels | lib/colony.mjs |
| Faceted low-poly poster art (flat vector landscapes, ambient seamless loops) | lib/lowpoly.mjs, references/styles.md § 5, examples/claude-balloon/ |
| Action / video-game feel: jumps, punches, hit-stop, shake, sparks, combo, boss bar | lib/fx.mjs, lib/rigs/critter.mjs, lib/rigs/bug.mjs, examples/claude-game/ |
| People (bean body, stick limbs, watercolour) | lib/rigs/bean.mjs |
| Timing, acting, cuts, camera, transitions | references/motion.md |
| Pick or match a look (editorial-texture, brush-watercolour, line-doodle, 3D type) | references/styles.md |
| Sound: SFX from the picture's timeline, a synthesised bed, loudness | references/sound.md, scripts/sound.mjs, scripts/music.mjs |
| Something broke | references/traps.md |
| What other animation skills do, and what we took | references/prior-art.md |
The library (lib/)
| file | gives you |
|---|---|
core.mjs | easing (eOut eIn eIO eBack eElastic eBounce eExpo popS), ss windows, hash rng noise1, catmull pathOf ik, canvas helpers (at line poly smooth ellipse stroke fill taper), texture (hatch fibre grainOver burst speedLines) |
pen.mjs | Pen: tapered brush stroke, pencil (3 broken passes), ring, box (overshooting corners), wash (blooming watercolour), text (writes itself), reveal-in-order, stable named seeds, opt-in boil |
textures.mjs | paper fibrePaper lightBands sun moon star4 grass soil nightSky fleshCells filmFinish |
nature.mjs | sprout melonLeaf tendril vine blossom bee drop |
rigs/ant.mjs | ant(ctx, x, groundY, s, pose) — the detailed ant (pose.look = ink / fill / tex layers for build-up reveals); antGuides() blue construction lines; seed() |
colony.mjs | leaf leafPiece egg larva cocoon seedGrain fungus roots nestCanvas (chambers + tunnels baked into soil, returns pathOf walkers) |
lowpoly.mjs | facetMass (bake a mass into lit triangles from a ramp, with dome / fade / haze), ridge, skyGradient, facetCloud, RAMPS (canyon, dusk, mesa, forest, ice, water, balloon, cloud) |
fx.mjs | timeWarp (hit-stop: game time freezes on contact, effects keep running), shake, burstParticles (spark / debris / dust / confetti / ember), landDust, ring, flashAlpha, comicText, floatText, afterimages, starburst, heart |
rigs/critter.mjs | a blocky action hero: run, jump, flip, squash & stretch, punch, kick, hurt, charge aura, expressions |
rigs/bug.mjs | a beetle enemy (and boss with horns): scuttle, jaw, flash, squash, spin |
rigs/chibi.mjs | a big-head cartoon person with real joints, styled by a look preset (hair, glasses, shirt, pocket + pen, pants, shoes): walk / run / jump / cheer / point / wave / carry, eyes, brows, lip-sync mouths, blush, sweat |
rigs/bean.mjs | person bust bubble flagCloth hat SKIN |
film.mjs | run({...}) → render / sheet / strip / verify; exposure(t, track, fps) for ones / twos / holds |
Install once per machine: cd <skill dir> && npm install (only dependency: @napi-rs/canvas). ffmpeg on PATH.
The loop
brief ─▶ style bible + beat sheet ─▶ film.mjs (copy the template) ─▶ sheet ─▶ fix ─▶ strip the fast bits ─▶ verify ─▶ render ─▶ cues.json ─▶ sound.mjs ─▶ look at the master's contact sheet ─▶ deliver
Hard rules
- Beats before code. Fill
templates/beat-sheet.md: every beat has an end state the viewer could point at, a camera, an exposure and a sound cue. Designing inside the code makes slides. - Every surface gets three layers: base → texture → edge. A flat fill is unfinished. The detail bible lists the texture for each material (fruit = packed cells + seeds with highlights, soil = hatch + strata + pebbles, chitin = gradient + form hatch + specular streak + rim light + setae…).
- Characters are rigs with anatomy, not blobs. Use
lib/rigs/ant.mjsfor insects; its local origin is the ground under the waist, soant(ctx, x, groundY, …)always stands on the ground. Never add a per-call "ground" offset (that exact knob produced stilt legs for two passes). - Boil is a decision, not a default. The textured-editorial look holds still shots perfectly still; the brush-watercolour look boils at 10 fps. Write the choice in the style bible.
- Stable seeds. Marks are seeded from a name (
pen.begin("ant/body")), never from the frame index, so a held drawing keeps its marks and a re-render is identical.node film.mjs verifymust pass. - Look at pixels, every pass.
sheetbeforerender,striparound every contact or fast action, and a contact sheet of the encoded master before you call it done. A render that exits 0 proves nothing. - Sound comes from the picture's timeline, ~0.03 s before each contact. No continuous pencil-scratch bed (tested, rejected: it fights everything). Loudnorm the mix.
- Show the world, not a slide. A setting needs layers (sky, far, mid, ground, foreground passing the camera), and a place needs inhabitants doing things. The camera moves through it.
Quick start
bashSK=~/.claude/skills/claude-animation # wherever this skill lives mkdir my-film && cd my-film && cp $SK/templates/film-template.mjs film.mjs CLAUDE_ANIMATION_LIB=$SK/lib node film.mjs sheet 0,1,2,3,4 # look CLAUDE_ANIMATION_LIB=$SK/lib node film.mjs render # out/template.mp4 node $SK/scripts/music.mjs bed.wav --dur 5 --end 4.4 node $SK/scripts/sound.mjs cues.json out/template.mp4 out/final.mp4 --bed bed.wav
Worked films in the repo: examples/money-quest/ — a 30 s two-hander adventure (the chibi rig + the critter);
examples/claude-balloon/ — a 30 s seamless ambient loop in faceted low-poly
(every motion periodic in 30 s, audio in 4 × 7.5 s bars so it loops too); examples/claude-game/ — a 30 s video-game short (platforming, bugs, a boss fight
with hit-stop, combo, special, K.O., chiptune from scripts/chiptune.mjs); and examples/ant-colony/ — 32 s, 16:9: a sketch → ink → colour → polish build-up,
a leafcutter cutting and carrying a leaf through a meadow, a dive into a nest cross-section (fungus garden,
nursery, queen, stores, tunnels full of traffic), 240 sound cues from the timeline; renders in ~27 s.
