h3-game-sprites

An Agent Skill for turning AI-generated video into 2D game sprite sheets.

Mortal Kombat (1992) filmed actors and digitized the footage into sprites. This does the same thing with a video model as the actor: one short clip per move, cut down to its pose extremes, chroma-keyed to transparency, and packed into an atlas you can drop into an engine. A character with eight moves costs about $5 and lands in an afternoon.

What it covers

• The character-still recipe: side view, planted feet, flat magenta backdrop, and the "no grain, no dust, no vignette" clause that keeps the chroma key clean.
• The idle pin: setting a move clip's first and last frame to the same idle still, so the character cannot drift off-model, every animation returns to neutral, and moves chain in a state machine.
• Clip briefs, including the guards that stop cartoon models ballooning fists on impact and the in-place ("treadmill") walk phrasing that keeps the engine in charge of movement.
• Frame extraction, keying with a despill that does not tint the character, and keyframe selection by cumulative motion arc-length rather than uniform sampling.
• Seamless walk-cycle detection, because whole-clip keyframes include the start-up and the settle back to idle, which is what makes a walk visibly reset instead of loop.
• The atlas and rendering math: one global scale (never per-frame normalization), anchoring from the ankle centroid, and the drawImage offset that decides whether your character stands on the floor or sinks through it.

Install

Copy the skill folder into wherever your agent looks for skills. For Claude Code:

git clone https://github.com/gary149/h3-game-sprites
cp -R h3-game-sprites/skills/h3-game-sprites ~/.claude/skills/

The format is portable across skills-compatible agents; adjust the destination directory to match your client.

Requirements

The local half of the pipeline (keying, keyframe selection, atlas building) needs only ffmpeg and Python 3 with Pillow and numpy. sprite_cut.py and build_atlas.py take an ordinary video file, so they work regardless of what produced it.

Generation needs a video model and an image model, and neither is pinned to one vendor. H3 / Hailuo 3 is served by aggregators such as OpenRouter and fal, and by MiniMax directly. The character still can come from whichever image model you prefer, or from an illustrator, as long as it follows the pose and flat-backdrop recipe in the skill. Budget roughly $0.60-0.70 per five-second clip and a few cents per still, varying by provider.

The bundled gen_still.py is a convenience, not a constraint: it defaults to Nano Banana (google/gemini-3.1-flash-image) through OpenRouter and reads OPENROUTER_API_KEY. Point the endpoint and model constants at the top of the file somewhere else, or skip the script and bring your own still.

Scripts

Script	Does
scripts/gen_still.py	Generate character and pose stills, with reference images and a parallel batch mode for style probes
scripts/sprite_cut.py	Extract, chroma-key, pick keyframes, emit a strip, a GIF and a metrics report; --loop finds a seamless cycle
scripts/build_atlas.py	Pack frames into an atlas at one global scale with shared anchors

Each runs standalone, so the pipeline is usable without an agent driving it:

python3 scripts/sprite_cut.py clips/punch.mp4 sprites/punch --frames 12
python3 scripts/sprite_cut.py clips/walk.mp4  sprites/walk  --frames 8 --loop
python3 scripts/build_atlas.py sprites/ atlas.json --moves idle,walk,punch --ref idle

Verifying, not vibing

Every stage emits numbers you can check: key purity per frame, how closely a move returns to its starting pose, feet drift, and on-screen pose heights. The guidance leans on this hard, because the failure modes here are visual and quiet. A sprite that renders at the wrong scale, or one that hangs below the floor, will pass any assertion written against atlas metadata alone. Measure the rendered canvas.

License

MIT