aldegad/sprite-gen

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

What is sprite‑gen?

sprite‑gen is a Python‑based command‑line tool (and a Codex/Claude skill) that turns a single static illustration of a game character into a complete, game‑ready sprite sheet. It does this by:

Prompting an image model (e.g., Grok Imagine, Codex, Claude) to generate a series of frames for each animation state (idle, walk, attack, …).
Removing the background chroma key and extracting clean, transparent PNG frames.
Assembling those frames into an atlas (sprite‑sheet‑alpha.png) together with a machine‑readable manifest (manifest.json.frame_layout) that tells a game engine the exact rectangle of each frame, its FPS and whether it loops.
Optionally generating loops from video clips, recolouring palettes, adding breathing idle loops, and even building simple scenes from multiple assets.

The tool is aimed at indie developers or hobbyists who want high‑quality pixel‑art sprites without manually drawing every frame.

Key features (as described in the README)

Feature	What it does	How you use it
Atlas‑row pipeline (A)	From one base image → a transparent sprite sheet + manifest. Includes automatic “breathe” idle loops.	`prepare → gen-set → extract → compose-atlas` (CLI commands).
Video‑to‑loop pipeline (B)	Generates a seamless transparent loop for each motion state by feeding the base image to a video model, then cutting the clip at its natural period.	`video-set` (creates jobs) → `video-canvas → video → video-frames → video-loop`.
Curation webview	Interactive UI to compare, reject or nudge generated frames before baking the final atlas.	`sprite-gen curation --run-dir <run>` (optional).
Utilities (C)	Cut out a single image, slice a multi‑cell sheet, unpack an existing atlas back into individual frames.	`cutout`, `slice-sheet`, `unpack-atlas`.
Post‑processing (D)	Deterministic recolouring, layer composition, export to Aseprite/Phaser/Flame formats.	`recolor`, `compose-layers`, `export-aseprite`.
Asset tools (E)	Create tiled backgrounds, generate projected shadows, inspect motion timing and contact points.	`background-tile`, `shadow`, `inspect-motion`.
Scene creation (S)	Combine several sprite atlases and other PNGs into a rendered scene (PNG, MP4, GIF) with camera and lighting metadata.	`scene-render`, `scene-inspect`.
Facing / handedness handling	Detects or forces left/right orientation for side‑view sprites; can mirror or re‑generate if wrong.	`--facing`, `--facing-fix` flags on `gen`/`video-set`.
Support for multiple providers	Works with Codex, Claude, Grok Imagine, and an explicit `openai` provider for server‑side use.	`--provider codex` etc.
Deterministic outputs	Same input → identical output bytes (important for version control).	`recolor-palette` + `recolor` pipelines.

Who might find it useful?

Indie game developers who need pixel‑art characters but lack the time or skill to hand‑draw every animation frame.
Pixel‑art hobbyists who want to experiment with AI‑generated motion loops while keeping full control over the final assets.
Tool builders who need a programmable way to generate sprite atlases for pipelines (e.g., CI for game assets).

Quick start (from the README)

# 1. Create a clean venv and install the package
python3 -m venv .venv && source .venv/bin/activate
pip install -e .

# 2. Generate an atlas from a single character image
sprite-gen prepare --out-dir run --character-id hero --base-image base.png
sprite-gen gen-set --run-dir run --provider codex   # generates rows of frames
sprite-gen extract --run-dir run                  # makes transparent PNGs
sprite-gen compose-atlas --run-dir run            # produces sprite-sheet-alpha.png + manifest.json

# 3. (Optional) Open the curation UI to tweak frames
sprite-gen curation --run-dir run

For video‑based loops, install RIFE once (sprite-gen rife install) and run the video-set workflow.

Limitations & caveats (as noted in the README)

The quality of generated frames depends on the underlying image/video model; the tool can only nudge or mirror frames, not guarantee perfect orientation.
Direction detection (--facing-fix) is record‑only by default and may be wrong even with high confidence.
Some pipelines (e.g., video loops) require external credentials (grok CLI login or XAI_API_KEY).
The “walk/run” cyclic loops are marked experimental until the motion QA passes.
Python 3.11+ is required; 3.10 is no longer supported.

License

Apache‑2.0 – free for commercial and non‑commercial use.

All information above is taken directly from the repository’s README; no external assumptions have been added.