sprite-gen README

The project's README from github.com/aldegad/sprite-gen. As one markdown file: README.md.

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.

Animated sprite-gen v2 showcase: paladin, wolf and slime

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 samurai and companions walking through a painted village with layered scenery and projected shadows

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.

Samurai Claudecy two-handed katana cut loop Samurai Claudecy one-handed katana cut loop Slime attack loop Hooded fox attack loop Paladin attack loop

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.

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] ~~~ 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

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 (aldegad/sprite-gen)

Searching Database…

2.9K ·GitHub
Sprite-gen
What is this?sprite-gen turns one base image into game-ready 2D sprite atlases or transparent motion-loop animations, packaged as a Codex/Claude coding-agent skill plus a standalone Python CLI.
Is this one tool or several pipelines bundled together?It bundles an atlas-rows pipeline (still to sprite sheet), a video-to-loop pipeline (still to transparent animation), independent utility and post-processing tool groups, and an optional scene-composition workflow; `sprite-gen --help` maps which commands belong to which.
How do I start generating sprites?Feed one base image into the atlas-rows pipeline (`gen`) to get a sprite-sheet-alpha.png with its manifest.json.framelayout; run `sprite-gen --help` first to see all pipeline groups, or install it as a Codex/Claude skill so your agent can drive the same commands.
What do I need for the video-to-loop pipeline?The atlas pipeline just needs Python 3.11+ with working venv/ensurepip, but the video-to-loop pipeline additionally needs ffmpeg, img2webp, and your own grok CLI login or an XAIAPIKEY since video generation isn't shipped with the repo.
Does the facing/direction detection always get it right?No — the direction detector is record-only by default and can misfire even when it reports high confidence; correcting it with --facing-fix mirror or --facing-fix regen is opt-in and should be reviewed before use.
What is Breathe?Breathe turns a still idle pose into a living loop by baking deterministic squash-and-stretch onto your curated frames from a single sidecar field, staying anatomy-aware and pixel-true.
What image and video providers does sprite-gen use?Image generation runs on codex and grok providers tied to a subscription you already pay for, plus an explicit-only openai provider for servers; motion loops are produced by Grok Imagine using your own grok CLI login or an XAIAPIKEY.
Can I export a finished sheet into a game engine?Yes, the post-processing stage supports Aseprite, Phaser and Flame exports alongside deterministic recolor variants and rig layer composites.
Why not just ask an image model for a sprite sheet directly?Direct prompts give you drifting poses, mismatched faces across frames, and backgrounds that won't key out; sprite-gen instead drives row-by-row generation, locks character identity, and strips to real alpha so the result is actually usable by a game engine.
What are similar projects?agent-sprite-forge, godogen, guizang-yingzao-skill, guizang-product-video-skill, 3dicon, onetake, shuohao-skills, livecanvas
Which topics is it in?spritesheet, game-dev, pixel-art, claude-skill, game-engine, gamedev, codex-skill, ai-tools, agent-skill, video-generation, image-generation, image-processing
Creator
aldegad
Size
62.3 MB
Stars
2.9K
Updated
CommitOct 17Releasev2.44.0Oct 09
Age
5mo
Commits · 90 Days