aldegad/sprite-gen: a component-row pipeline for game-ready sprite atlases
Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
At a glance
- What is it?
- sprite-gen is a Codex/Claude skill plus a Python CLI that turns one still image into a transparent sprite atlas with a runtime manifest, or into transparent motion loops cut from a video model's output. It is aimed at developers who need consumable assets, not demo images.
- Who is it for?
- Adopt sprite-gen if you already drive an image or video model and need the last mile done properly: real alpha, on-grid pixel art, and a manifest.json.frame_layout your engine samples instead of guessing a grid. Skip it if you want a hosted, no-setup generator or a guarantee that walk and run cycles will pass; the README states cyclic locomotion stays experimental unless motion QA actually passes.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 17, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap sprite-gen targets: demos that no engine can load
Ask an image model for a sprite sheet and the README describes the usual result in plain terms: a character whose face changes every frame, a background that will not key out, poses that overlap and drift off-grid, and a PNG your engine cannot consume. That is the problem statement this project is built around, and it is a narrow one. sprite-gen does not generate the artwork itself. It drives a generation model row by row, then does the unglamorous work after that: locking identity across frames, stripping the chroma background to real alpha, extracting each pose as a clean transparent frame, and baking a runtime atlas with a machine-readable manifest.json.frame_layout.
The audience follows from that. This is for a solo developer or a small team already using Codex or Claude as a coding agent and willing to run a Python CLI beside it. It is not for someone who wants a browser tab that produces a sheet in thirty seconds. The README positions the tool as a skill first and a CLI second, and both halves matter: the agent handles the request conversation, the CLI does the pixel work.
Two ordered pipelines and a set of independent tools
The README's own map splits the project into lettered groups. Pipeline A, atlas rows, runs prepare, then gen or gen-set, then extract, then compose-atlas, with an optional curation step that can sit between extraction and composition. Pipeline B, video to loop, runs video-canvas, video, video-frames, video-loop, and produces per-state seamless transparent GIF, WebP or strip output, animated by Grok Imagine and cut at the clip's own period. Groups C, D and E are not ordered flows at all: cutout, slice-sheet and unpack-atlas are utilities; recolor, compose-layers and the export commands are post-processing; background-tile, shadow and inspect-motion are asset tools that take independent PNGs or animations. Group S is optional scene creation, which consumes finished assets plus a scene.json and renders PNG frames, MP4 or GIF.
That grouping is the most useful thing in the README, because it tells you where the coupling is. Only A and B are flows. If you want a repeating background tile or a projected shadow, you do not need to run generation at all. The project version 2.2.0 release note, dated 2026-09-12, is titled independent asset tools and optional scenes, which matches that split.
Installing sprite-gen and baking a first atlas
The README gives a three-line install and is explicit that the virtualenv is the only supported interpreter. Pillow and NumPy are the runtime dependencies; pyproject.toml pins pillow between 12.3.0 and 13, and numpy between 2.2.6 and 3.
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
sprite-gen --helpRunning sprite-gen --help prints the pipeline map and groups commands by the code domain that owns them, so it doubles as the command index. The README's quickstart then opens pipeline A with sprite-gen prep, and the atlas flow continues through generation, extraction and composition.
sprite-gen prepWhat you should end up with, per the README, is sprite-sheet-alpha.png plus manifest.json.frame_layout. The manifest carries absolute frame rectangles, per-state fps and loop flags. That is the detail that separates this from a folder of PNGs: your engine samples rectangles rather than assuming a uniform grid, which matters because the README states poses are held to a single measured grid rather than a nominal one.
One packaging note worth knowing before you file a bug. The build backend requires setuptools 77 or newer, and pyproject.toml explains why in a comment: the PEP 639 string form of the license field is rejected by older setuptools. The comment states that 76.1.0 fails with a license validation error and 77.0.1 builds, and that the floor went unnoticed because pip's build isolation fetches the newest setuptools anyway. If you pin your build environment, pin it at 77 or above.
Breathe, chroma unmixing and the Backbone Lattice
Three mechanisms carry most of the output quality, and each has a doc of its own. Breathe takes a still idle pose and bakes a deterministic squash and stretch loop onto curated frames, driven from a single sidecar field, and the README describes it as anatomy-aware and pixel-true. It is baked during composition, not applied at runtime, so the cost lands at build time.
The alpha path is the second. The README states the extractor unmixes rather than peels, and links a doc explaining why, with the result verified against white backgrounds so no chroma fringe survives. That distinction is the difference between a sprite that looks clean on a dark background and one that looks clean everywhere.
The third is the Backbone Lattice, which the README says measures one grid for the whole subject and holds every cut to it. This is where the project is opinionated: pixel art stays on grid or it is not pixel art. The trade-off is that you inherit the measured grid. A subject whose proportions do not fit a single lattice is a problem the README does not claim to solve.
Where sprite-gen is the wrong tool
The clearest limitation is stated by the project itself: cyclic locomotion such as walk and run stays experimental unless motion QA actually passes. That is not a footnote. Walk cycles are the single most common thing a 2D game needs, and the README does not promise them. If your project depends on reliable walk and run animation, treat pipeline A as unproven for that case and plan to curate.
The second limitation is the dependency on an external generation model. Pipeline A drives generation row by row and pipeline B hands a still to a video model; the README names Grok Imagine for the video path. Nothing here generates art offline. If you cannot reach a provider, or you need deterministic output from a fixed input with no model in the loop, the generation half of this project is unavailable to you. The deterministic claims in the README attach to recolor, which bakes N variant sheets from a palette map with same input, same output bytes, and to the extraction path's byte-identity contract, not to the model calls.
The third is operational. The README calls the virtualenv the only supported interpreter, and the dependency floors are tight: Python 3.10 or newer, with a NumPy floor chosen specifically because 2.2.6 is the newest release with CPython 3.10 wheels. Someone on 3.9 or on a managed environment that pins NumPy 1.x is outside the supported set.
How it differs from a hosted sprite generator
The obvious alternative is a hosted AI sprite generator, the kind the search data shows people looking for: something that takes an image or a prompt and returns a sheet in a browser. The difference in approach is where the work happens. A hosted generator owns the whole path and hands you a finished image. sprite-gen owns only the post-generation path, and it hands you a file plus a manifest.
That changes what you can do with the result. A hosted tool's output is whatever grid it chose; sprite-gen's manifest.json.frame_layout gives absolute frame rectangles with per-state fps and loop flags, so the engine reads the layout instead of inferring it. A hosted tool also gives you no say in the alpha method. sprite-gen documents unmixing rather than peeling, and verifies against white backgrounds.
The cost is setup and control. You run a Python CLI, you manage a virtualenv, you bring your own generation access, and you accept that the agent-driven request flow expects Codex or Claude. If your team has no agent in the loop and no appetite for a local toolchain, the hosted route is shorter. If your bottleneck is assets that survive contact with an engine, the extra steps are the product.
Maintenance, licence and what the docs do not cover
The repository is not archived, and the last push was on 2026-09-17, one day before this was written. Releases are frequent and small: v2.1.0 on 2026-09-10, v2.1.1 on 2026-09-11, v2.2.0 on 2026-09-12. The changelog titles describe narrow, specific changes rather than rewrites, and pyproject.toml carries a release discipline note asking that the package version stay synchronized with SKILL.md's version field in the same release commit. That is a good sign for upgrade cost: patch-level releases with described scope are cheaper to absorb than periodic large ones.
Licensing is Apache-2.0, declared in pyproject.toml in the PEP 639 string form, with a LICENSE file and a NOTICE file at the repository root. Apache-2.0 includes an explicit patent grant and requires attribution via the NOTICE file when you redistribute. That is a general property of the licence, not legal advice; check how it interacts with your own distribution before shipping.
What the documentation does not settle is version-to-version migration. The README documents the current command groups; the changelog titles describe what changed in each release, but the README does not document rollback or a compatibility policy for the manifest format. If you generate atlases in CI and a future release changes frame_layout, you would be reading the changelog to find out. Pin the version you build against until you have checked.
Editorial conclusion
Adopt sprite-gen if you already drive an image or video model and need the last mile done properly: real alpha, on-grid pixel art, and a manifest.json.frame_layout your engine samples instead of guessing a grid. Skip it if you want a hosted, no-setup generator or a guarantee that walk and run cycles will pass; the README states cyclic locomotion stays experimental unless motion QA actually passes. Verify first that your Python is 3.10 or newer, that you can install into a fresh virtualenv (the README calls the venv the only supported interpreter), and that you have a provider your agent can reach, since the pipeline drives generation row by row rather than generating locally.
Frequently asked questions
Is there a free AI sprite generator available?
sprite-gen is open source under Apache-2.0 and installs from the repository with pip install -e . in a virtualenv, so the tool itself costs nothing. It does not generate art on its own: the pipelines drive an external generation model, and the README names Grok Imagine for the video path, so any cost there sits outside the project.
Can ChatGPT generate sprites?
The README does not describe ChatGPT as a provider. sprite-gen is presented as a Codex/Claude skill plus a Python CLI, and the generation pipelines call an image or video model row by row rather than producing sprites inside a chat session.
How do I generate a sprite from an image with sprite-gen?
The README's quickstart installs into a virtualenv, runs sprite-gen --help to print the command map, then opens pipeline A with sprite-gen prep. From there the atlas flow runs generation, extraction and composition, and produces sprite-sheet-alpha.png with manifest.json.frame_layout.
What format does sprite-gen output for a game engine?
It writes a transparent atlas, sprite-sheet-alpha.png, alongside manifest.json.frame_layout, which the README describes as carrying absolute frame rectangles, per-state fps and loop flags. The README also lists Aseprite, Phaser and Flame exports under post-processing.
Does sprite-gen support walk and run animation cycles?
The README states that cyclic locomotion such as walk and run stays experimental unless motion QA actually passes. It does not promise those cycles, so plan to use the optional curation view to review the loop before baking.
Community notes