--- name: character-animation description: Give a 2D game's hero animation that reads well and never slows the controls, drawn in code (pixel art), using numbers measured frame by frame from Celeste, Hollow Knight and Shovel Knight - a state list with frame budgets, a run at 3-4 steps a second with held drawings, a rigid head that bobs 1-2 px, hidden far arms, hair or a scarf as tapered blobs that move with the drawings, no-wind-up jumps and held landings, free asset and AI options, contact sheets and a head measure to check it, and a script to measure a reference clip the user provides. Use when the user says the character looks stiff, robotic, lifeless, jittery, shuffling or "like a sticker", the head bobs, the scarf or hair looks strange, or asks for animation, more frames, a run cycle, anticipation, hair, scarf or cape motion, or how a real game animates its hero. --- # Character animation A small hero looks alive when every state has a clear pose, the drawings change on a steady beat, the head moves as one piece and one loose part trails after the body. In a game, the player's input always comes first: animation shows what the body is already doing and never makes it wait. Don't invent motion: these rules come from measuring Celeste, Hollow Knight and Shovel Knight frame by frame ([references/measured-games.md](references/measured-games.md)), the twelve principles of animation ([references/principles.md](references/principles.md)) and published pixel-art run cycles ([references/sources.md](references/sources.md)). This skill's scripts are in `${CLAUDE_SKILL_DIR}/scripts/` (the references write `` for this folder). The pixel-art, game-juice and platformer-levels skills sit next to it, at `${CLAUDE_SKILL_DIR}/../`, if the game used them. ## Always do 1. **List states and transitions first.** Before drawing anything, write down every state the hero can be in (idle, run, turn, rise, fall, land, air jump, bounce, death, respawn) and the event in the code that starts each one. Note what the game already shows for each (a frame, a squash, particles). Read this from the code, don't guess. See [references/states.md](references/states.md). 2. **Never delay the controls.** The body moves on the frame the input arrives. No wind-up before a jump or attack (none of the three games has one); at most a take-off stretch of up to 4 frames while the body is already rising. Nothing holds the body or blocks the next input; any new input ends a drawn beat at once. 3. **Run on a cadence.** 6–8 drawings, each held 4–5 game frames, for 3–4 steps a second at full speed. Choose the cadence; don't derive it from foot contact or try to plant the feet. The feet slide 3–5× in all three games and nobody sees it. Other states start from the table in [references/timing.md](references/timing.md). See [references/run-cycle.md](references/run-cycle.md). 4. **The head is one rigid piece.** Stamp it from one shared drawing so the face can't drift. It bobs 1–2 px in whole pixels, only when the drawing changes, lowest on contact; never 0 px frozen, never tilted, tweened or moved between drawings. 5. **No thin far arm.** A 1 px far arm is invisible at 1× and the run reads one-armed. Hide it (a cloak, a prop held across the body) or show it as a 1–2 px patch one shade darker. Legs are short dark blocks with a big swing (feet far apart, back foot kicked up), not stubs that shuffle. 6. **Check the design can animate before animating it.** Look at the hero at 1× against the real background and ask: does the head read as a head (round, a clear face opening, no ear-like tips)? Is one thing clearly the brightest (a lantern, a sword, the face) so the eye follows it? Do the body and the head contrast, so the run reads from the body's shape? If not, redraw the hero's design within the same frame size and hitbox, keeping its colours, props and silhouette recognisable: for example hide the arms in a darker cloak and let a held prop be the near hand, as Hollow Knight and Shovel Knight do. Say what you changed and why, and keep the old look behind the `?anim=0` switch. 7. **One loose part, as tapered blobs that move with the drawings.** Hair, a scarf or a cloak hem: 4–5 overlapping blobs (radius at least 1 art px) with a dark outline, trailing 25–40% of the hero's height, never above the shoulder. It changes when the body's drawing changes and lags about one drawing: back when running, down when rising, up when falling. Use `SecondaryMotion.follow()` in `scripts/secondary-motion.js`, updated only on drawing changes; no per-frame physics, which breaks into dots or a stiff rod. See [references/secondary-motion.md](references/secondary-motion.md). 8. **Jump, land, idle, turn.** One rise drawing and one fall drawing, switched at the apex. Landing: one drawing held 5–7 frames, 1–2 px lower, with a few dust pixels, then straight back to run or idle. Idle nearly still (a blink or a 1 px breath at most). Turn: an instant flip. 9. **Show the hero's state on the hero.** A spent double jump or dash recolours the loose part or the prop on the frame it is used, with a short white flash when it comes back. With "reduce motion" set, drop spins and big squash. 10. **One owner of scale.** If the game already squashes and stretches (game-juice), that code owns scale. A drawn landing or stretch pose adds to it, so lower the juice for that event until the total matches. Never add a second scale tween. The body follows the physics. 11. **Never change how the game plays.** Animation is drawn on top. Don't touch bodies, velocities, timers or input. Put all the numbers in one settings object with a switch (for example `?anim=0`) that gives back the old look. 12. **Check it and report.** Add the `window.__anim` hook and film every state with `scripts/anim-sheet.mjs` before and after, with `--head` for the head's travel and step rate. Look at the contact sheet at 1× and slowed. The body must move identically (`--compare`), and the game's measurement and tests must give the same results. Write renders outside the game folder and never commit them. See [references/checking.md](references/checking.md). ## Optional: study a reference When the user wants their hero to move like a particular game, measure it instead of guessing: `scripts/study-reference.mjs` takes a clip the user provides (for example their own recording), the game's native resolution and a box around the hero, and gives drawing holds, capture stutter and contact sheets in real sprite pixels. Never download footage from YouTube or other sites; ask the user for the file. Keep the clip and its frames out of the game folder and any repo, and publish only numbers. See [references/checking.md](references/checking.md). If the user would rather not draw, [references/assets.md](references/assets.md) lists free CC0 character sets that can go into a public repo, and the paid AI tools, with their catches. ## Not now New moves and mechanics, hitbox changes and sound. Leave skeletal rigs, shaders, a new character or a bigger hero until the user asks.