sprite-gen
One drawing in. Game-ready sprites out — as an atlas, or as transparent motion loops.
English · 한국어 · 日本語 · 简体中文 · Español · Français
Voting is open until October 5 (KST). sprite-gen is an entry in Wanted AI Championship 2026. If it has saved you time, a vote would mean a lot (Wanted login and a Korean phone check required).
Help cover the model API costs of developing sprite-gen with an optional GitHub sponsorship. Choose your amount and a one-time or monthly contribution.
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.
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.
v2.5.3 attack loops straight out of the video pipeline: one still each, Grok Imagine clip, frames gate, automatic loop selection. No manual cut points.
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.
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.
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).
- 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).
Quickstart
# 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 --help
A · 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, breathe
B · 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 result
C · 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 / Flame
E · 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.json
S · 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.json
The agent-facing workflow, gates and contracts live in SKILL.md.
Install as a skill
python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
--repo aldegad/sprite-gen --path . --name sprite-gen
Image 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.11+; CI runs only 3.14. Python 3.10 is no longer supported. The quickstart needs a Python with working venv/ensurepip.
Attribution
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.
License
Apache-2.0
sprite-gen 把一张基础图片变成可直接用于游戏的 2D 精灵图集或透明循环动画,以 Codex/Claude 编码 agent 技能加独立 Python CLI 的形式打包。