H3 Game Sprites Agent Skill

H3 → Game Sprites

Mortal Kombat filmed actors and digitized the footage into sprites. Do the same

with H3 as the actor: one 5 s clip per move (~$0.64), cut down to 8–16 pose

extremes, keyed to transparency, validated with numbers rather than vibes.

Read the h3-video skill for H3 API mechanics (submitting, polling, frame

pinning, the parallel runner). This skill is the sprite layer on top of it.

Why a 5-second clip becomes a quarter-second move

The video is source footage, not gameplay. 5 s at 24 fps is ~120 frames; a game

move needs 8–16. H3's slow, deliberate performance is an advantage — more

in-betweens to choose from, less blur per frame. Game timing (startup, active,

recovery) is authored separately in frame data and never inherited from the clip.

1. The character still

Generate with scripts/gen_still.py (Nano Banana, ~$0.07, --batch for parallel

style probes). The prompt must nail four things:

• **Side view facing right, full body including feet, centered, feet planted on

an invisible ground line.** Cropped feet make a character you cannot anchor.

• **Flat solid magenta #FF00FF, edge to edge, no gradient, no cast shadow, no

ground line.** This is your chroma key.

• **Clean cel: no film grain, no dust, no scratches, no paper texture, no

vignette.** Beautiful grain destroys the key — say so explicitly, because

style prompts tend to add it.

• Bold outlines and flat fills survive downscaling to sprite size.

Style choice is a motion question, not a taste question: some styles H3 simply

won't animate. Probe several looks, then spend one clip motion-testing the

finalist before committing to a full move set. Ink wash, claymation, rubber-hose

and photoreal move well; flat vector and paper cutouts risk freezing.

Extra end-pose stills (KO, downed) are generated from the idle as a reference

image. Say **"EXACTLY ONE character, completely alone, no second figure, no

duplicate"** — asking for "knocked out" while showing a standing reference

reliably returns both a standing and a lying character in one frame.

2. Clip briefs, one per move

The idle pin. Every move clip sets `first_frame = last_frame = the idle

still`. This buys three things at once: the character cannot drift off-model

(H3 keeps identity only when it is anchored in a locked frame), the animation

returns exactly to neutral so it loops, and moves chain cleanly in a state

machine. Moves that end elsewhere (KO) pin their own end frame instead.

Use the beat structure from h3-video, plus these sprite-specific guards —

each one was learned by getting the opposite:

The character's hands and feet stay their normal size at all times - NO
ballooning, NO growing fists; limbs may stretch but hands and feet keep
constant scale.
Camera locked on a tripod, no zoom, no pan, no cut.
The background stays a perfectly flat uniform solid magenta at all times - no
gradient, no cast shadow, no ground line, nothing else enters the frame.
The character stays centered on the same ground level and does not travel
across the frame; everything not described stays static.
Audio: SFX only. NEVER generate music, melody, score or musical tones.

• Walks are briefed in place ("as if on a treadmill") — the engine moves the

transform, so a sprite that travels fights the engine.

• Hit-stun and KO react to "an invisible blow", since no opponent is in frame.
• Cartoon models love exaggeration. Unforbidden, fists balloon on impact frames.

A basic set — idle, walk forward, walk back, jump, crouch, punch, kick, block,

hit-stun, KO — is ~$6.50 and submits as one parallel batch. Consider skipping

the back-walk clip and playing the forward cycle in reverse (a classic 2D

fighter trick): asked for a backward stride, H3 tends to give a wary sway.

3. Decompose and validate

python3 scripts/sprite_cut.py clips/v_punch.mp4 sprites/punch --frames 12
python3 scripts/sprite_cut.py clips/v_walk.mp4  sprites/walk  --frames 8 --loop

Writes keyed/*.png (RGBA), strip.png, anim.gif (pose preview at source

pacing) and report.json.

Keyframes are picked by cumulative motion arc-length — equal steps of

accumulated frame-to-frame change, so frames concentrate where the action is.

Uniform sampling looks mushy, and picking local motion maxima over-samples the

idle bounce at the head of the clip.

--loop for cycles. Whole-clip picks include the start-up and the settle

back to idle, which is exactly why a walk visibly resets instead of looping.

Loop mode finds the closest-matching frame pair inside the sustained middle of

the clip and samples between them, giving a true seam.

Read the summary before trusting anything:

| metric | what it tells you |

|---|---|

| worst_bg_purity | ~1.0 means every pixel is confidently background or character; lower means key leak |

| loop_diff | move returns to its start pose (or, in loop mode, the cycle seam) |

| first_vs_last_baseline | feet end where they began, in px |

| baseline_drift_px | feet wandering — large is right for a jump, suspicious for a stance |

Despill note: do not blend the fringe toward the off-channel, which visibly

tints the character. Clamp the key channels against the off-channel instead, as

the script does.

4. Atlas: one global scale

The trap. Scaling each frame to a fixed on-screen height is the obvious

thing and it is wrong: a crouch or jump tuck has a *smaller* bounding box, so

per-frame normalization renders it bigger than standing. Derive one scale

from the idle frame and apply it to every frame of every move.

python3 scripts/build_atlas.py sprites/ atlas.json \
    --moves idle,walk,jump,crouch,punch,kick,block --ref idle --height 340

Frames are stored trimmed, at global scale, with offsets to a shared anchor:

footOffset (feet vs the ground line), anchorOffset (stance-center column

inside the crop), driftX (this frame's drift from the canonical center).

The anchor X comes from the ankle-region centroid, not the bbox center — a

big arm or tail swing moves the bbox, and centering on it makes the character

slide sideways between poses.

The script prints per-move on-screen heights. Crouch and jump-tuck must be

*shorter* than idle; if they are taller, per-frame scaling has crept back in.

5. Render

ctx.translate(x + f.driftX, GROUND_Y + jumpY);
ctx.scale(facing, 1);              // player 2 is a flip, never a generative mirror
const foot = state === 'jump' ? 0 : f.footOffset;   // engine arc supplies the lift
ctx.drawImage(img, -f.anchorOffset, foot - img.height, f.w, f.h);

Two real bugs live in those four lines. drawImage's y is the top edge

while footOffset positions the feet, so dropping - img.height sinks the

character through the floor. And if the engine authors a jump arc, adding the

frame's baked-in air offset on top double-lifts it.

Frame data stays separate from pixels — durations per frame, a loop flag, and

for held states an enter/hold/release split so a key can be held:

punch:  { frames:[0..11], durations:[35,35,45,50,...], loop:false }
crouch: { enterFrames:[0,1,2], holdFrame:3, releaseFrames:[4..7], hold:true }

Roughly 35–70 ms per frame for attacks (fast startup, slower recovery) against

~150 ms for idle. Tune feel here; never regenerate video for timing.

6. Verify with pixels, in a browser

Asserting on atlas metadata is not verification — it passes happily while the

render is broken. Measure the character on the actual canvas:

// drive the loop deterministically: requestAnimationFrame freezes in unfocused tabs
const drive = (n, codes) => {
  for (const c in keys) delete keys[c];
  for (const c of codes) keys[c] = true;
  for (let i = 0; i < n; i++) tick(g, keys, 16.7);
  draw();
};
// then getImageData, find the non-background bbox, compare against GROUND_Y

Confirm: idle feet sit on the ground line, crouch is shorter *and still

planted*, jump lifts without resizing, landing returns to exactly idle.

Chrome extensions cannot open file:// URLs — serve the page with

python3 -m http.server and drive localhost.

Costs and habits

Still ~$0.07, 5 s clip $0.64, a 10-move fighter ~$7, failed jobs free. Retakes

are per-move, never the whole set, so diagnose before rerolling: a wrong-looking

character means the locked frames were wrong, not the prompt. Keep superseded

assets rather than deleting them — an earlier take is often the only surviving

copy of a pose you end up wanting back.