sprite-gen

English · 한국어 · 日本語 · 简体中文 · Español · Français

---

Ask an image model for a "sprite sheet" and you know what you get: a character whose face changes every frame, a background that won't key out, poses that overlap and drift off-grid, and a PNG your game engine can't actually consume. Cute demo, useless asset.

sprite-gen is a Codex/Claude skill and a Python CLI that closes that gap. Give it one base image — it drives generation row by row, locks the character's identity, strips the chroma background to real alpha, extracts each pose as a clean transparent frame, and bakes a runtime atlas with a machine-readable manifest.json.frame_layout. Or hand the same still to a video model and get back a seamless, transparent loop per motion state. For the last 10% that generation never gets right, a curation webview lets you compare, reject, nudge and watch the loop live before you bake.

For side sprites, video-set uses --facing right|left consistently across canvas placement and clip prompts. Its direction detector is record-only by default (--facing-fix none) and can be wrong even at high confidence. Use gen --ref image.png --facing right to request orientation in the generation prompt; gen otherwise preserves orientation. Prompts request direction but cannot guarantee the result. Correction is opt-in: --facing-fix mirror, or gen --facing-fix regen; review the still before using either. See facing options.

Start with a request

Ask for sprites or an image. The agent checks access, asks only for missing provider/motion choices, runs the existing pipeline, and delivers the files. The curation view is optional. Save your choices once to reuse separate sprite and image defaults; a one-off request does not overwrite them. User workflow and defaults.

Pipelines, independent tools and scenes

The two sprite pipelines are ordered generation flows. Tool groups contain independent commands; scene creation is an optional workflow that consumes finished assets. sprite-gen --help prints this map and groups commands by the code domain that owns them.

flowchart LR
    subgraph A["A · atlas rows"]
        direction LR
        a1[prepare] --> a2["gen · gen-set"] --> a3[extract] --> a5[compose-atlas]
        a5 -.-> a4["curation (optional)"]
        a4 --> a5
    end
    subgraph B["B · video → loop"]
        direction LR
        b1[video-canvas] --> b2[video] --> b3[video-frames] --> b4[video-loop]
    end
    subgraph C["C · utilities"]
        direction LR
        c1[cutout] ~~~ c2[slice-sheet] ~~~ c4[ui-kit] ~~~ c3[unpack-atlas]
    end
    subgraph D["D · post-processing"]
        direction LR
        d1[recolor] ~~~ d2[compose-layers] ~~~ d3[export-*]
    end
    subgraph E["E · asset tools (independent)"]
        e1[background-tile] ~~~ e2[shadow] ~~~ e3[inspect-motion]
    end
    subgraph S["S · scene (optional)"]
        s1["existing assets + scene.json"] --> s2[scene-render]
        s1 --> s3[scene-inspect]
    end

Full index: docs/README.md. Architecture with domain and pipeline diagrams: docs/architecture.md.

What you actually get

• A transparent sprite atlas (sprite-sheet-alpha.png) — real alpha, no leftover chroma fringe, verified against white backgrounds (why the extractor unmixes instead of peeling).
• A runtime manifest (manifest.json.frame_layout) — absolute frame rectangles, per-state fps and loop flags. Your engine samples rectangles; it never guesses a grid.
• Breathe — a still idle becomes a living loop, deterministic squash & stretch baked on your curated frames from one sidecar field, anatomy-aware and pixel-true (details).
• Pixel-art that stays on grid — the Backbone Lattice measures one grid for the whole subject and holds every cut to it (details).
• Motion loops from video — jumps get a tall canvas, attacks a wide one, the loop point is the clip's own period, and a one-shot action is cut rest → action → rest (details).
• Deterministic colourways — recolor bakes N variant sheets from a palette map; same input, same output bytes (details).
• QA you can watch — per-state GIFs and contact sheets, so motion is judged as motion before anything ships. Cyclic locomotion (walk/run) stays experimental unless motion QA actually passes.
• Independent asset tools — build repeating backgrounds, project shadows from a foot anchor, and inspect timing, duplicate poses and contact evidence. Ambiguous feet produce an unverified measurement (details).