One drawing in. Game-ready sprites out — as an atlas, or as transparent motion loops.
English · 한국어 · 日本語 · 简体中文 · Español · Français
Each character started as one still image. Grok Imagine brought it to life; sprite-gen extracted the transparent loops, and HyperFrames assembled this showcase.
A separate village composition made from sprite-gen assets. This GIF preserves the 10-second video at 20 fps with a 256-colour palette.
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.
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.
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] ~~~ 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
| Pipeline / tool group / workflow | What goes in → what comes out | Docs |
|---|---|---|
| A · atlas rows | one still + a list of states → sprite-sheet-alpha.png + manifest.json.frame_layout, with Breathe baked on idle poses |
run-contract · breathing |
| B · video → loop | one still → per state, a seamless transparent GIF / WebP / strip, animated by Grok Imagine and cut at its true period | video-pipeline · video |
| C · utilities | an imported image or grid sheet → clean transparent cuts; a finished atlas → a curator-ready run | sheet-slicing · curation |
| D · post-processing | a finished sheet → deterministic colourways, rig layer composites, Aseprite / Phaser / Flame exports | recolor · layer-tracks · engine-export |
| E · asset tools | independent PNGs or animations → repeating tiles, projected shadows, motion/contact measurements | asset-tools |
| S · scene | existing assets + placement, camera and lighting → PNG frames, MP4/GIF, inspection and placement metadata | scene |
Full index: docs/README.md. Architecture with domain and pipeline diagrams: docs/architecture.md.
- 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 —
recolorbakes 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).
- Optional scene creation — place existing PNGs, external frame sequences, loop strips or runtime atlases on named planes, with camera motion and shared shadow projection. Sprite generation can finish before this step (details).
# install (Pillow, NumPy) into a fresh virtualenv — the venv is the only supported interpreter
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
sprite-gen --helpA · atlas rows — one still to a runtime atlas.
sprite-gen prepare --out-dir <run> --character-id <id> --base-image base.png # request, guides, prompts
sprite-gen gen-set --run-dir <run> --provider codex # every state row, 4 at a time
sprite-gen extract --run-dir <run> # chroma → transparent frames
sprite-gen compose-atlas --run-dir <run> # sprite-sheet-alpha.png + manifest.json
sprite-gen curation --run-dir <run> # (optional) pick, nudge, breatheB · video → loop — one still to transparent loops (needs ffmpeg, img2webp, and your own grok login or XAI_API_KEY).
sprite-gen video-set --base side=still.png --states idle,walk,run,jump,attack --out-dir set/
# per item: video-canvas → video → video-frames → video-loop; set/table.md names every resultC · utilities — each stands alone.
sprite-gen cutout icon.png --white-check # white/ivory → matte, magenta/green → chroma engine
sprite-gen slice-sheet --sheet sheet.png --chroma-key magenta --grid 3x2 # multi-figure sheet → per-cell cuts
sprite-gen unpack-atlas --atlas sheet.png # finished atlas → curator-ready run (or --pngs-dir folder/)D · post-processing — refine a finished sheet without regenerating.
sprite-gen recolor-palette --base <run>/sprite-sheet-alpha.png --out palette.draft.json
sprite-gen recolor --run-dir <run> --spec recolor.spec.json # → <run>/variants/
sprite-gen compose-layers --run-dir <run> # rig runs: declared stacks → <run>/layers/
sprite-gen export-aseprite --run-dir <run> # Aseprite JSON for Phaser / FlameE · asset tools — each accepts existing assets, including artwork from other tools.
sprite-gen background-tile --source background.png --period 512 --overlap 32 --out tile.png
sprite-gen shadow --source walk.strip.json --out-dir shadows/
sprite-gen inspect-motion --source walk.strip.json --out motion.json
# Only with known same-foot contact and an isolated foot ROI:
sprite-gen inspect-motion --source walk.strip.json --contacts 0:4 --foot-box 20,70,32,10 --out stance.jsonS · scene — an optional composition workflow. The scene contract includes a complete spec.
sprite-gen scene-render --spec scene.json --out-dir render/ --formats png,mp4 --export-layers
sprite-gen scene-inspect --spec scene.json --out scene-check.jsonThe agent-facing workflow, gates and contracts live in SKILL.md.
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
--repo aldegad/sprite-gen --path . --name sprite-genImage generation is part of this engine (sprite_gen.gen, providers codex and grok on a subscription you already pay for, plus an explicit-only openai provider for servers and SaaS that bills per call; the general image-gen skill is a thin shuttle over it). Video uses your own credential — the grok CLI login or an XAI_API_KEY — and nothing is shipped with the repo (docs/video.md).
sprite-gen supports CPython 3.10+; CI runs 3.10 and 3.14. The quickstart needs a Python with working venv/ensurepip.
The component-row workflow is inspired by the Apache-2.0 licensed hatch-pet skill, but targets generic game sprite atlases and includes no pet packages or pet visual assets.
Community contributions, experiments, and their originating pull requests are documented in CONTRIBUTORS.md.
Apache-2.0
