animated-spritesheets

Animated Spritesheets

Turn a character into a packed, engine-loadable spritesheet by generating one labeled pose-board image — a grid of the same character in the frames of an action — then recovering/slicing it. This is the image-generation method.

Why image generation, not image-to-video. One generation per action keeps identity consistent (cloak/face/weapon stay the same across frames); video morphs the character mid-clip. Trade-off: fewer frames (a model reliably lays out ~4–12 grid cells, not a long strip), so motion is choppier — per-frame pose labels + pixel-snapping make the few frames count.

The happy path

You are an agent. All scripts run with node <script> — no Python, no uv, and nothing to install: each imports a bundled, dependency-free scripts/_lib/.

# This skill's directory. Claude Code substitutes CLAUDE_SKILL_DIR (project, global
# or plugin install); other agents fall back to wherever `skills add` put it.
SKILL="${CLAUDE_SKILL_DIR}"
[ -d "$SKILL" ] || for d in .agents/skills .claude/skills ~/.agents/skills ~/.claude/skills; do
  [ -d "$d/animated-spritesheets" ] && SKILL=$d/animated-spritesheets && break
done

# 0. (once) An approved character anchor PNG on a flat chroma matte (the identity
#    reference). Make it via the pixel-art skill, or:
node $SKILL/scripts/sprite-prompt.mjs anchor --direction e --chroma '#00FF00'   # -> vg generate run

# 1. ASK what the action needs (frame count / fps)
node $SKILL/scripts/sprite-presets.mjs --action attack --json

# 2. PROMPT — get the labeled pose-board prompt (per-frame semantic poses on an
#    implied 4x3 grid, identical-character + no-shadow litany, the craft):
node $SKILL/scripts/sprite-prompt.mjs pose-board --action attack --direction e --frames 8 \
  --frame-prompt-style specific --pose-board standard --style lobit-v1 --chroma '#00FF00'

# 3. GENERATE the pose board with the anchor as the identity reference. The board
#    is a 4-col x 3-row grid; the first N cells are the frames (4:3 aspect). Use 2K
#    so each cell clears ~512px — pixel snapping (step 4) needs that resolution to
#    recover a clean grid:
vg generate run fal-ai/nano-banana-pro/edit --prompt "<from step 2>" \
  --image_urls '["<anchor_url>"]' --aspect_ratio "4:3" --resolution "2K" \
  --download attack-board.png --json

# 4. PROCESS into runtime frames with ONE command. Default = naive uniform slice
#    (the robust path). Add --recover to re-center a pose that drifted off its cell
#    (it falls back to the uniform slice if it can't, so passing it is always safe):
node $SKILL/scripts/process-sheet.mjs attack-board.png --action attack --rows 3 --cols 4 --frames 8 --out-dir runs/hero-attack