# Agent Sprite Forge Languages: [English](./README.md) | [繁體中文](./README.zh-TW.md) | [简体中文](./README.zh-CN.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)

Agent Sprite Forge banner

0x0funky%2Fagent-sprite-forge | Trendshift

Agent Sprite Forge 0.4 teaser
0.4 launch teaser: every frame is real ASF output.

## One still → a whole game-ready sprite set

Approve one generated still. Get every action of the character, keyed, looped, timed and exported for your engine.

Agent skills for Claude Code (plugin), Codex and Grok. The agent generates a master still with the best image route you have, makes one image-to-video clip per action from it, and deterministic Python tools gate, key, register, loop, retime, finish and package every action for Godot, Aseprite or a web game.

Aria, the approved master still: a young swordswoman with short dark hair, a teal cloak and a long red scarf, side view facing right
1. One approved master still
Generated by the local Codex CLI (image_gen), take 1 of 3.
Aria's six actions at real timing: idle, walk and run loops; attack, jump and hurt one-shots
2. Six actions, one image-to-video clip each
Grok image-to-video (local CLI), soft-matte keyed, registered, loops picked by measurement, one-shots retimed to game speed, HD finish with the colour lock. Real timing.

Aria runs across a generated meadow, stops for a sword thrust and runs on
3. In a scene: the packaged run, attack and idle over a generated background. The run speed is measured from the contact foot, so the feet do not slide. Every frame comes from the 2026-10-06 live run; nothing is mocked up.

Pixel looks · Hibit style · What's new · Quickstart · Routes and providers · Pipeline · Maps · Showcase · Tools

## New: pixel looks, 1x sprites that follow a reference

A fight on a 384x216 plate: a swordsman walks in and is struck by a skeleton knight, strikes back, a mage casts and the knight falls, a frost dragon roars and lunges, and after the last blow it falls and the swordsman raises his sword
A whole fight from pixel-look sprites, rendered at 1x and shown at 2x: four 1x characters (masters of 33x55 to 87x86) and 14 sets with 168 drawings read back from image-to-video clips. The plate behind them is a generated painting brought down to 384x216 and 40 colours. The white hit flashes and the knight's fade are the demo's; nothing else is added.

An image model asked for pixel art paints a picture of pixels: blocks of uneven size (15 to 30 px in the picture below), 88,410 colours in one small figure, soft edges. Shrinking it does not help: resized plainly to the sprite's size it still has 1,033 colours. Hibit gets round this by never asking for pixel art. **Pixel looks** go the other way, for the classic small sprite that follows a look you like: the look is never described in words, one sprite you like is the reference for the whole cast, and the picture the model paints is read back onto a real grid. `pixel_look.py master` finds the picture's own grid, takes one flat colour from every block, keeps the figure's proportions, brings the colours down to a palette and closes the outline by rule. What comes out can be counted: 33x55 pixels, 48 colours, alpha 0 or 255, a 2.5 KB PNG.
The picture an image model painted of a silver-haired swordsman in a dark coat, on a flat green ground: it looks like pixel art
What the image model painted
1254x1254 px. The figure alone has 88,410 colours and its blocks are 15 to 30 px: no grid fits it.
The same picture resized plainly to 33x55 and shown at 7x: a smudged eye, uneven edges and green specks at the hair
Resized plainly to 33x55
Nearest sampling, shown at 7x: 1,033 colours, the ground's green left in 3 cells. Bilinear gives 1,275 colours and 413 soft pixels.
The 1x sprite made from the same picture, shown at 7x: clean cells, a closed outline, a clear face
pixel_look.py master
The same picture read on its own grid, shown at 7x: 33x55, 48 colours, no soft pixel.

The same part of the face twice: in the picture the blocks have uneven sizes and soft, stained edges; in the sprite every cell is one flat colour
The same part of the face: the picture at 2x (left) and the sprite at 40x (right).

The swordsman, the mage, the skeleton knight and the frost dragon on one ground line; each idles and plays one action in turn: a sword strike, a cast, a strike, a roar
The cast follows the first sprite. Every further character is drawn beside the first sprite in one picture (ask-cast, cast), so it keeps the pixel size and stands as tall: a mage, a skeleton knight and a frost dragon, 48 colours each.

The swordsman's idle, walk, attack, hurt and victory sets and the dragon's roar, lunge and fall, each with its number of drawings
Poses, views and motion from the master. A pose is the master reproduced with one change (the sword pose: 217 cells changed, 91% of the master kept); a view is drawn beside the master. Motion comes from an image-to-video clip of that sprite: pixel_motion.py reads every frame back on the sprite's lattice and palette (the attack: 21 drawings picked from 145 video frames). The number is the drawings of each set.

| Measured on the run (2026-11-12) | | |---|---:| | The swordsman's generated picture (the figure) | 1254x1254, 88,410 colours, blocks 15-30 px | | The same picture resized to 33x55: nearest / bilinear | 1,033 colours / 1,275 colours and 413 soft pixels | | `pixel_look.py master` | 33x55, 48 colours, 0 soft pixels, 2.5 KB | | The cast: mage / skeleton knight / frost dragon | 45x56 / 50x55 / 87x86, 48 colours each | | The sword pose from the master | 217 cells changed, 91% of the master kept | | The attack set from one clip | 21 drawings from 145 video frames | | The fight | 14 sets, 168 drawings; every drawing has only its sprite's own colours and no soft pixel | What's new: - **`pixel_look.py`** (generate2dsprite): `ask-master` and `master` draw the figure you like again, alone and large, and read it as the 1x master; `ask-cast` and `cast` draw every further character beside the master; `ask-pose`, `pose`, `ask-view` and `view` make poses and side or back views from the master; `lineup` puts everything on one ground line and reports the heights. - **`pixel_motion.py`** (video2dsprite): `prepare`, `frames`, `finish`, `measure`, `breath`: the frames of an image-to-video clip read back on the sprite's lattice and palette, a loop or an action picked from them, and an `animation.json` 3.0 package with nearest sampling. - **Only on request.** Nothing else changes: the HD, pixel and hibit finishes and their defaults are untouched. - The reference sets the look (pixel size, shading, outline); the characters are your own. The whole route, what you accept and when, and its limits: [references/pixel-looks.md](./skills/generate2dsprite/references/pixel-looks.md). ## New: hibit, real pixel art from flat AI art

Pip's Star Grove: Pip the fox mage casts falling stars at magma slimes crawling in from both sides while coins drop
Pip's Star Grove, a one-screen demo built only from hibit output: autopilot gameplay captured from the game canvas (480x270, shown at 2x). FX: pixelfx by Patch (MIT).

Never ask an image model for "pixel art": it paints fake, uneven pixels. The **hibit** style asks it for clean flat lineless art (at most 3 tones per material, no outlines) and makes the pixels afterwards: one palette per character learned from the source pixels, an 8x8 majority-vote downscale (every pixel is the palette colour that covered most of its cell, never a blend), hysteresis against flicker, eyes and glints kept, binary alpha, and a 1 px outline whose colour comes from the sprite itself.
Pip's flat lineless master still, the hibit finish of her idle at 80 px shown at 4x, and her 17-colour palette with the outline colour
Flat art in, pixel art out
The approved master (Codex) and the hibit finish of the idle at 80 px: 16 colours learned from the source plus the outline colour, which --outline auto takes from the sprite's dominant hue (#380500, a deep red-brown from the orange fur). Never a fixed orange.
Pip idle, walk, cast and hurt, and the magma slime idle, crawl and attack, at 2x and real timing
Whole sets, one palette per character
Pip (idle, walk, cast, hurt) and a magma slime (idle, crawl, attack): Grok image-to-video clips through sprite_set.py --finish hibit, 12 fps. Every action reuses the first action's palette and outline.
### FX: pixelfx (recommended) or the image route For hibit effects we recommend **[pixelfx](https://github.com/patch-gg/pixelfx)** by Patch: a library of code-driven pixel-art effects (fire, arcane, impacts, weather, pickups, UI) that fits the style and renders for free on your machine. It is a separate MIT project: clone it yourself (`git clone https://github.com/patch-gg/pixelfx`, Node 18+) and the skill finds it. `fx_pixelfx.py check` picks the route; a route you name wins. | | A: pixelfx installed (recommended) | B: image route (always available) | |---|---|---| | Frames per effect | 16-91 at 30 fps | 4 (one 2x2 sheet) | | Cost | free (local Node) | one generated image per effect | | Look | pixelfx's own style, recoloured with `--ramp` and `--snap` | your game's flat style and palette | | Credit | every render ships `CREDITS.txt` (pixelfx's MIT license and notice) | the image route, like every sprite |
Route A: pixelfx star-fall recoloured to Pip's palette hits the slime, then a hit spark, a smoke poof and spilling coins
A: pixelfx
arcane/star-fall recoloured to Pip's palette, impacts/hit-spark, spawn/poof, spawn/coin-drop.
Route B: image-generated falling stars hit the slime with a ground burst, then white puffs and bouncing coins
B: image route
Codex 2x2 FX sheets, keyed and registered by process, made pixel art by the hibit_fx.py step (Pip's palette for the stars and coins, 6 learned colours for the spark and the poof).
Full 50 s of autopilot play, same seed: [with pixelfx FX (MP4)](./src/hibit/pip-star-grove-pixelfx.mp4) · [with image-route FX (MP4)](./src/hibit/pip-star-grove-imagegen.mp4). | Measured on the live run (2026-11-06) | | |---|---:| | Pip: palette (learned from the source pixels) | 16 + outline | | Noise flicker removed by the hysteresis (vs the same majority without it): Pip's 4 clips / the slime's 3 | 32-40% / 10-24% | | Auto outline colour: Pip / magma slime / Forge Bot | #380500 / #380500 / #002131 | | Colours in the whole game scene: route B / route A (pixelfx light blending; only the star-fall snapped) | 65 / about 6,700 | | Frames per effect: route B / route A | 4 / 16-91 | What's new: - **`master_still.py --finish hibit`**: masters as flat lineless cel-shaded art, the input the hibit finish wants. - **`finish_frames.py hibit`** and **`sprite_set.py plan --finish hibit`**: the palette, the 8x8 majority-vote downscale, hysteresis, lone-pixel cleanup and the outline (`auto`, a `#RRGGBB`, `selective`, `dark` or `none`); 80 px heroes, 12 fps, nearest sampling in the engine export. - **`hibit_plate.py`** (generate2dmap): 480x270 backgrounds (x4 = 1080p) with a 14-colour palette, a paper-cut smoothing pass and shade maps for lighting and hit flashes without new colours. - **`fx_pixelfx.py`** (`check`, `list`, `render`) for route A and **`hibit_fx.py pixelize`** for route B.

Forge Bot idle: the earlier bold pixel finish next to hibit with the auto, selective and fixed orange outlines
Forge Bot: the earlier bold pixel finish, then hibit with the outline from the image (auto), the palette's shades (selective) and a fixed studio orange.

## What's new in 0.4 — the big upgrade Before 0.4, character animation meant cutting frames out of an image-generated sheet, or keying a single clip by hand. 0.4 turns one approved still into the whole set: one image-to-video clip per action, and a measured pipeline from every clip to the engine. Before and after, measured on real outputs:
Old pixel fox run cut from one image-gen sheet next to the new 0.4 pixel fox run, 4x nearest, 80 ms per frame
Pixel finish: the 48x64 fox run
Old: one image-gen sheet cut 1/8 (594–709 colours per frame, soft alpha). New: master still → Grok clip → pixel finish (16–19 colours, binary alpha, selective outline). 4x nearest, both at 80 ms.
2x crop of the same Grok frame: a magenta outline with the old keyer, a clean edge with the 0.4 soft matte
Soft-matte keyer: no purple fringe
Same Grok clip, same frame, 2x crop. Fringe 0.704 → 0, leaked key pixels 7,780 → 0, keying 271 s → 44 s for 145 frames.
Aria's attack at the generator's slow-motion speed next to the auto-retimed attack at game speed
One-shots retimed to game speed
Image-to-video plays a quick attack as a slow-motion clip. retime --auto-oneshot cuts the frozen holds and pins the hit: 4.1 s → 0.7 s, hit at 292 ms.
Aria's run loop without and with the HD colour lock; without it the boots shimmer olive and maroon
HD colour lock
Video models drift colours on fast limbs. The lock holds every design colour on the master's (OKLab chroma, lightness kept): hue flips halve and most of the boot shimmer goes away.
| Measured on the live runs | before | 0.4 | |---|---:|---:| | Pixel fox (48x64, 8 frames): colours per frame | 594–709 | **16–19** | | Pixel fox: alpha levels | 199 | **2** | | Pixel fox: lone pixels per frame (mean) | 732 | **75** | | Keyer: purple fringe (outer-ring spill, mean) | 0.704 | **0** | | Keyer: key pixels leaked over 145 frames | 7,780 | **0** | | Keyer: time for 145 frames | 271 s | **44 s** | | Attack: one-shot length | 4.1 s | **0.7 s** | | Colour lock: hue flips per frame pair (run loop) | 352 | **170** | | QC: good takes wrongly rejected | 18 of 24 | **0 of 24** | What changed: - **Image generation first.** Every image and clip goes through one command, `route_media.py`: your API key if you configured one (OpenAI, Google Gemini, xAI, BytePlus, fal.ai), else your signed-in Codex or Grok CLI, else code art as the last resort. See [Routes and providers](#routes-and-providers). - **One master still per character.** `master_still.py` writes the prompt, generates takes, fixes a near-miss by edit and approves one still (`master.json`). - **A whole set from that still.** `sprite_set.py` makes one image-to-video clip per action, gates every take (area, feet, identity, zoom, turning around, edges, background, extra objects, motion, end pose, colour bleed, timing), retakes with fix clauses, keys with a soft matte, registers, picks loops, retimes one-shots, finishes and packages. - **HD finish by default, crisp pixel finish on request.** One body scale per character from the master. The pixel finish adds a crisp downscale, a spaced palette of at most 32 colours, a selective outline and binary alpha. - **Colour lock** on every action of a set, and **QC recalibrated** on 42 labelled live takes. - **Engine exports.** animation.json 3.0 with a PNG atlas, VP9-alpha WebM and packed-alpha MP4, decoded and verified; Godot SpriteFrames and Sprite3D; Aseprite JSON; maps for Tiled, Godot and LDtk. - **Claude Code plugin**, plus Codex and Grok installs. Hardened on Windows: Codex sandbox run folders, locked-file cleanup, cp1252/cp950 consoles. Everything in the [CHANGELOG](./CHANGELOG.md). The live record, weak points included: [docs/validation-2026-10-06.md](./docs/validation-2026-10-06.md). ## Quickstart ### 1. Install **Claude Code (plugin)** ```bash claude plugin marketplace add 0x0funky/agent-sprite-forge --sparse .claude-plugin skills claude plugin install agent-sprite-forge@agent-sprite-forge python -m pip install "numpy>=1.26" "Pillow>=10.1" "scipy>=1.11" ``` `--sparse` checks out only the plugin manifest and the skills, not the showcase media. **Codex** ```bash git clone https://github.com/0x0funky/agent-sprite-forge.git cd agent-sprite-forge python -m pip install -r requirements.txt python tools/install_skills.py --apply --host codex ``` **Grok**: from the same clone, `python tools/install_skills.py --apply --host grok` (`~/.grok/skills`). `--host agents` writes `~/.agents/skills` and `--dest ` any skills folder. `--apply` backs up an installed copy and writes a sha256 manifest; `python tools/install_skills.py --check --host codex` reports drift later. Video needs ffmpeg 5.1+ on `PATH`. Start a new agent session so the skills load. Optional: configure an API key ([Setting API keys](#setting-api-keys)). Without one, the agent uses your signed-in Codex or Grok CLI. ### 2. Make the master still ```text Use $generate2dsprite to make a master still of Aria, a young swordswoman hero: short dark hair, a teal hooded cloak, a long red scarf and one steel sword. Side view, facing right, HD. ``` The agent runs `master_still.py generate --takes 3` (every take through `route_media.py`), shows you the takes, fixes a near-miss with `master_still.py edit` ("THE ONLY CHANGE: ..."), and approves one: the still is keyed, padded to the class framing (a hero stands 788 px tall on 1024x1024) and recorded in `master.json`.

Three master takes of Aria side by side on the magenta key colour; take 1 was approved

### 3. Make the sprite set ```text Use $video2dsprite to animate the approved Aria master: idle, walk, run, attack, jump and hurt. Package them for Godot and the web. ``` Under the hood (`` is the installed `video2dsprite` folder): ```bash python "/scripts/sprite_set.py" plan --master art/aria-master/master.json --output-dir art/aria-set python "/scripts/sprite_set.py" run --plan art/aria-set/set_plan.json python "/scripts/sprite_set.py" review --plan art/aria-set/set_plan.json python "/scripts/sprite_set.py" accept --plan art/aria-set/set_plan.json --action run --take 2 python "/scripts/sprite_set.py" report --plan art/aria-set/set_plan.json ``` `run` resumes where it stopped and never generates a clip twice. The agent looks at every review sheet before it accepts an action, because the numbers cannot see a changed weapon or a covered face. Each action ends as a verified package; `export_engine.py` adds Godot and Aseprite files. ## Routes and providers Every generated image or clip goes through `generate2dmedia/scripts/route_media.py`. It walks this order and names the route it used: | Order | Route | Images | Video | Used when | |---|---|---|---|---| | 1 | **API**: a key you configured | OpenAI, Google Gemini, xAI, BytePlus Seedream, fal.ai (reference edits) | xAI, BytePlus Seedance, fal.ai (Kling v3, Veo 3.1, Luma, MiniMax, Wan, Vidu, LTX) | A key is configured. The key is your consent, so there is no per-call question | | 2 | **Local CLI**: your own signed-in Codex or Grok | Codex `image_gen` (up to 8 references); Grok one-shot image or edit | Grok image-to-video in ACP mode (6 or 10 s) | No key, or every API route refused for an account reason (no key, auth, quota, rate limit). Uses your subscription quota, never an API key | | 3 | **Code art** (`codeart2d`) | Code-drawn pixel sprites, vector art, FX, tiles | Rigged animation | The last resort: only when no route exists (`no-route`, exit 3) or when you ask for code-drawn art. Always disclosed as code-drawn | `python "/scripts/route_media.py" resolve --kind image` prints the route that would run, and `forge_doctor.py` lists which keys are configured (yes or no, never the key) and the resolved order. A moderation refusal, or an outcome that may have cost money, is never retried on another route. ### Supported providers | Provider | Key variable | Images | Video | Pins the last frame | Notes | |---|---|---|---|---|---| | OpenAI | `OPENAI_API_KEY` | generate and edit, 16 references, native alpha | none | n/a | `gpt-image-2.5-sunburst` by default | | Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | generate and edit, 14 references | none | n/a | Pro model for hero masters; SynthID watermark | | xAI | `XAI_API_KEY` | generate and edit, 5 references | 1–15 s, 480p–1080p | yes (1.5 at 480p or 720p), up to 4 keyframes | Lite model for drafts | | BytePlus ModelArk | `ARK_API_KEY` | Seedream generate and edit, 10 references | Seedance, 4–15 s | yes | activate the models first; no real faces | | fal.ai | `FAL_KEY` | reference edits (Nano Banana 2 and Pro, Seedream 5, GPT Image 2) | Kling v3, Veo 3.1, Luma Ray 3.2, MiniMax H3, Wan 3.0, Vidu Q3, LTX-2.5 | yes, on every curated model | Veo and LTX get the still padded to 16:9; the crop box is recorded | Each model's limits are checked against [capabilities.json](./skills/generate2dmedia/references/capabilities.json) before anything is sent; a request the model cannot take is skipped with the reason or adapted with a note (for example a video length snapped to one the model renders). Every clip is published without audio. Details: [route-media.md](./skills/generate2dmedia/references/route-media.md), [api-usage.md](./skills/generate2dmedia/references/api-usage.md), [provider-survey.md](./skills/generate2dmedia/references/provider-survey.md), [cli-routes.md](./skills/generate2dmedia/references/cli-routes.md). ### Setting API keys Each provider reads only its own key, from the environment or from one JSON file in your user configuration folder (never inside a project); the environment wins. | System | Config file | |---|---| | Windows | `%APPDATA%\agent-sprite-forge\config.json` | | macOS, Linux | `~/.config/agent-sprite-forge/config.json` (or `$XDG_CONFIG_HOME/agent-sprite-forge/config.json`) | ```json { "OPENAI_API_KEY": "sk-...", "GEMINI_API_KEY": "...", "XAI_API_KEY": "xai-...", "ARK_API_KEY": "...", "FAL_KEY": "key-id:key-secret", "providers": {"order": {"image": ["gemini", "openai"], "video": ["byteplus"]}} } ``` Every field is optional. `providers.order` puts your favourite providers first; `models` picks a model per provider and tier. Keys are read in-process only: never printed, logged, written, passed on a command line or handed to a child process, and a provider never uses another provider's key. On macOS and Linux keep the file private (`chmod 600`). ### Spend records Every call, paid or local, is a line in `/.forge/ledger.jsonl` with its estimate, the provider's job id and the artifact's sha256, and each output folder keeps a `job.json`. There is no cap unless you set one: `--budget-usd`, `--max-calls`, `FORGE_MAX_PAID_REQUESTS`, and `FORGE_SESSION_IMAGES` / `FORGE_SESSION_VIDEOS` for the local routes. `media_ledger.py summary` shows the totals. ## Pipeline: master → set → finish → export ```text master still one clip per action cut finish package and export master_still.py --> sprite_set.py run --> gait_loop.py select --> finish_frames.py --> engine_export.py package + verify generate, edit, route_media.py video, (loops), retime.py hd (default) or export_engine.py (Godot, Aseprite) approve gates, retakes, soft --auto-oneshot pixel, colour lock matte, registration (one-shots) to the master ``` | Step | Tool | What it does | |---|---|---| | Master | `master_still.py` | Takes through `route_media.py`, a fix by edit, then `approve`: keyed, padded to the class framing, `master.json` with the identity recap every motion prompt repeats | | Clips | `sprite_set.py run` | One image-to-video clip per action from the master, on a per-action canvas (jump 3:4 with headroom, attack 16:9); idle and attack pin their last frame where the route can | | Gates | `sprite_set.py` | Area, feet, identity, zoom, turning around, edges, background, extra objects, motion, end pose, colour bleed, timing; up to 3 takes with fix clauses, else the best usable window | | Key and register | `video2dsprite.py process`, `register_clip.py` | Soft matte with one profile per character; the inverse of the recorded input transform, so the body scale never pumps | | Cut | `gait_loop.py`, `retime.py` | Walk, run and idle loops chosen by measurement; one-shots retimed to game length with the hit pinned (attack 0.7 s, jump 0.9 s, hurt 0.5 s) | | Finish | `finish_frames.py` | HD: one scale per character, premultiplied area downscale, clean alpha, colour lock. Pixel: crisp downscale, shared spaced palette, selective outline, binary alpha, optional fixed cells (`--canvas 48x64`) | | Package | `engine_export.py` | animation.json 3.0, PNG atlas, WebM alpha, packed MP4, poster; `verify` decodes every file | | Review | `sprite_set.py review`, `accept`, `report` | Contact sheets, finished strips and a cast line-up for the agent to look at; the report lists routes, takes, QC numbers, loops and timing | ### Engine exports | Target | What you get | Tool | |---|---|---| | Web and any engine | `animation.json` 3.0 (whole-ms durations, events, anchor), PNG atlas, VP9-alpha WebM, packed-alpha H.264 MP4 for iPhone, poster; `forge-runtime.mjs` and a WebGL packed-alpha compositor | `engine_export.py package`, then `verify` | | Godot 4 | SpriteFrames `.tres` with an AnimatedSprite2D `.tscn`; an AnimatedSprite3D package | `export_engine.py --target godot-spriteframes`, `godot-sprite3d` | | Aseprite, Phaser, PixiJS | Aseprite JSON array atlas with frame tags, events and the pivot | `export_engine.py --target aseprite-json` | | Maps | Tiled 1.10, Godot 4.3+ (TileMapLayer scene), LDtk 1.5.3 | `export_tiled.py`, `export_godot.py`, `export_ldtk.py` |

The new pixel fox run as an 8-frame sprite sheet, 48x64 cells, shown at 4x
The pixel fox as shipped: 8 frames, 48x64 cells, 80 ms each, with Godot, Aseprite and web packages (sheet shown at 4x).

> **Editor imports are not verified yet.** The exporters prove parse-level round trips, and Tiled exports are re-rendered at 0 px difference; nobody has opened the 0.4.0 Godot, LDtk or Aseprite exports in the editors. ## Maps `generate2dmap` makes maps instead of isolated sprites: painted layered maps (a ground-only base, a dressed reference, a prop pack, then anchored transparent props), tiles and autotiles, side-scroll stages and HD-2D battle plates. Collision, reachability and exits come from data (`map_bundle.v2`, `map_nav.py`), with exports to Tiled, Godot 4 and LDtk and a single-file walkable HTML preview.
Ground-only cyberpunk canal base map
Ground-only base
Dressed cyberpunk canal reference map
Dressed reference
Generated 3x3 cyberpunk canal prop pack
3x3 prop pack

Layered cyberpunk canal map with y-sorted props
The layered map: anchored props sorted on their ground lines

## Showcase: games made with Agent Sprite Forge Original games and characters, assembled with Codex and the skills in earlier releases. They show the full loop: generated assets, structured scene data and playable prototype wiring.
Summon Survivors Unity WebGL gameplay
Summon Survivors — Unity WebGL
Generated map art, hero sheets, summons, evolutions, enemies, bosses, pickups, HUD, FX, level-up choices and a WebGL build.
Play build · Build conversation
Forest Pass Defense Godot tower-defense map
Forest Pass Defense — Godot tower defense
A Godot 4 prototype with map, separated props, tower slots, towers, enemy sheets, boss and flying enemies, waves, HUD, build/upgrade/sell flow, projectiles and targeting rules.
Generate2DMap Godot editor scene
Editable RPG map — Godot TileMap
An image-generated tileset and prop sheet wired into editable TileMapLayer, Sprite2D props, encounter grass Area2D, StaticBody2D collision, exits, metadata and a debug player and camera.
Neon Breach cyberpunk side-scroller
Neon Breach — cyberpunk side-scroller
A playable side-scroller prototype built around generated character, attack, map and gameplay assets.
Sengoku Era JavaScript RPG starter selection
Sengoku Era — JavaScript monster RPG
A browser RPG prototype with generated characters, starter selection, map flow and battle UI.
Play build
Sengoku Era JavaScript RPG battle scene
Starter selection and battle loop
A compact JavaScript game built from sprite, monster, battle and map assets made with the skills.
More Godot tower-defense output
Forest Pass Defense enemy roster
Enemy roster, including flyer and boss units
Forest Pass Defense tower icons
Tower lineup
Forest Pass Defense HUD icons
HUD and gameplay icons
- `scenes/ForestPass.tscn` with base map, separated props, enemy paths, tower slots and HUD nodes. - Six tower families with generated tower art and upgrade stages. - Animated enemy sheets for ground units, flying units and boss encounters. - Wave, difficulty, tower catalog, collision, route and tower-slot metadata. - Runtime build, upgrade, sell, projectile and targeting behaviour connected in Godot.
More Unity survivors-like output
Summon Survivors Unity WebGL gameplay with summons, enemies, pickups, HUD and objective
Summons, enemies, pickups, HUD and objective flow
Summon Survivors Unity WebGL level-up menu
Level-up choices: summon unlocks, training, stats and recovery
- `Assets/Survivors/Scenes/SummonSurvivors.unity` as the playable scene. - `SurvivorContentDatabase.asset` connecting generated hero, summon, enemy, pickup, HUD and FX sprites. - Starter summon selection, survival objective, XP and coin pickups, level-up choices, summon training and evolution flow. - Enemy spawning pressure, boss timing, projectile attacks, area damage, health bars and score tracking. - WebGL build output under `Builds/WebGL` with Vercel deployment config.
Godot editable TileMap: the meadow layers
Godot meadow layered RPG map preview
Layered map preview
Godot meadow debug preview with collision and zones
Collision and zone debug overlay
Image-generated Godot meadow tileset atlas
Image-generated tileset atlas
Image-generated 3x3 meadow prop pack
3x3 generated prop pack
### FX and sheet sprites Sheets stay the route for FX, icons and props: casts, projectiles and impacts come from `$generate2dsprite` sheets.
Fire mage cast animation
Spell cast
Fire mage projectile animation
Projectile
Earlier character output (0.3): four-direction walk sheets and the Ryo video case study Characters were cut from image-generated sheets before 0.4; 0.4 animates them from one master still instead.
Samurai walking down
Down
Samurai walking left
Left
Samurai walking right
Right
Samurai walking up
Up
The 0.3 video pipeline on Ryo (base still → 6 s image-to-video → chroma key → 16-frame strip); the 0.4 keyer's numbers on this clip are in the [CHANGELOG](./CHANGELOG.md). | Base still | Motion (image-to-video) | Sprite result (16 frames) | | --- | --- | --- | | Ryo base still on magenta | Ryo 6 s run video preview
[Download MP4](./src/video2dsprite-ryo/run-6s.mp4) | Ryo 16-frame run loop |

Ryo 16-frame run strip
Short skill intro (MP4): intro.mp4

### Code art: the last-resort fallback When no image route exists, or when you ask for code-drawn art, `codeart2d` draws it from a spec with no image model and no quota, and says so. These are rendered from [`skills/codeart2d/examples`](./skills/codeart2d/examples).
Code-drawn pixel hero walk cycle
rig_animate.py: FK/IK walk with planted feet
Code-drawn slash, impact ring, dust and projectile FX
fx_build.py: slash, impact, dust and projectile with hit events
Code-made top-down meadow map with roads, a pond, houses and trees
autotile_build.py + layout_build.py: seam-proven tiles, every exit reachable
## Included skills Keep the five skill folders together: they call each other's scripts by relative path. | Skill | Use it for | Main outputs | | --- | --- | --- | | [`generate2dsprite`](./skills/generate2dsprite) | Master stills, characters, creatures, props, icons and FX; sheets for FX, icons and props; packaging frames from any source | `master.json`, registered frames, clips with ticks and events, palettes, QA, Aseprite/Godot exports | | [`video2dsprite`](./skills/video2dsprite) | A whole sprite set from one master still (`sprite_set.py`), or one supplied clip | Gated, soft-keyed, registered, looped or retimed, finished frames; animation.json 3.0, WebM alpha, packed MP4, PNG fallback | | [`generate2dmap`](./skills/generate2dmap) | Top-down and side-scroll maps, tiles, prop kits, parallax, HD-2D plates | map_bundle.v2, collision and navigation checks, Tiled/Godot/LDtk exports, HTML preview, scene loops | | [`generate2dmedia`](./skills/generate2dmedia) | The route to every generated image and clip (`route_media.py`), the five API providers, the local Codex/Grok CLI routes, the capability check | Media with receipts, ledger lines, route proofs | | [`codeart2d`](./skills/codeart2d) | Code-drawn pixel sprites, flat vector art, FX, autotiles, layouts, parallax: the last resort, or on request | Exact-palette frames, clips, fx.v1 runtime, seam-proven tilesets, playable bundles, `codeart-meta.json` | In Codex, `codeart2d` and `generate2dmedia` are explicit-only: the sprite, video and map skills route to them. ## Tools Run from your project root as `python "/scripts/.py" ...`. Every tool has `--help`, writes a new output folder (it never replaces one), prints one JSON line and exits 1 on failure (4 when it published a result whose QA failed, for inspection; 3 when a generation has no route). The SKILL.md files hold the routing tables. | Skill | Tool | What it does | | --- | --- | --- | | generate2dsprite | `master_still.py` | `prompt`, `generate --takes N`, `edit`, `pad`, `approve`: one approved master still per character, `master.json` | | | `generate2dsprite.py process` | Keys (soft or hard), slices and registers a sheet on one sampling grid; pipeline-meta v2 with QA | | | `sheet_qc.py` | `spill` finds parts crossing cell lines before slicing; `frames` checks identity, NEAR/FAR leg alternation, drift | | | `scale_frames.py` | One scale and root per action; the canvas grows, nothing is clamped | | | `plan_guide.py`, `make_anchor_layout.py`, `make_layout_guide.py` | Sheet planning, pose guides and fixed-scale templates for an image tool | | | `build_animation_clips.py` | Clips v2: 60 Hz ticks, events, transitions, hit-stop, review sheets and lints | | | `assemble_frames.py` | Packs whole frames losslessly; ownership slicing, loop seams, ambient crossfades | | | `palette_tool.py`, `pixel_reduce.py` | OKLab palettes, locks, variants, flicker-free clip quantizing; integer pixel-grid reduction | | | `export_engine.py` | Aseprite JSON, Godot SpriteFrames and AnimatedSprite3D (imports not yet verified) | | | `fx_pixelfx.py`, `hibit_fx.py` | Hibit FX: `check` picks route A (pixelfx installed) or B; `render` pixelfx effects with their credits; `pixelize` image-route FX sheets into hibit pixel art | | | `pixel_look.py` | Pixel looks (on request): `ask-master`/`master`, `ask-cast`/`cast`, `ask-pose`/`pose`, `ask-view`/`view`, `lineup`: 1x sprites that follow a reference, read on the picture's own grid; the cast, the poses and the views all come from one master | | video2dsprite | `sprite_set.py` | `plan`, `run`, `review`, `accept`, `retake`, `report`: one clip per action from one master, gates, retakes, finish and packages | | | `finish_frames.py`, `colour_lock.py` | HD (default), pixel or hibit finish, shared palettes, cast line-up; colour lock to the master and its measurement | | | `pixel_motion.py` | Pixel looks motion: `prepare`, `frames`, `finish`, `measure`, `breath`: clip frames read back on the sprite's lattice and palette, sets packaged with nearest sampling | | | `video2dsprite.py` | `key-plan`, `triage`, soft-matte `process`/`clean`, `package`, `verify`, `doctor` | | | `prepare_i2v_input.py`, `register_clip.py` | Registration by construction: input on a recorded transform, one inverse transform back, take QC | | | `gait_loop.py`, `retime.py`, `animation_review.py` | Measured walk/run/idle loops and stride; one-shot auto retime and impact/hold timing on ticks; classified candidates | | | `engine_export.py`, `validate_animation.py` | animation.json 3.0 with WebM alpha, packed MP4 and mobile tiers behind a residue gate; decoded verify; contract check | | | `references/runtime/forge-runtime.mjs`, `packed-alpha-webgl.mjs` | Distance-driven walks, hit-stop, transitions; WebGL packed-alpha compositor | | generate2dmap | `extract_prop_pack.py` | Anchored transparent props with footprints and despill (prop_pack.v2) | | | `extract_terrain_tiles.py`, `extract_platform_strip.py` | Terrain fills, overlays, iso/hex and Wang rows; platform caps with surface and seam QC | | | `compose_layered_preview.py`, `validate_parallax.py`, `conform_background.py` | Ground-line sorted previews with audit overlays; parallax coverage and seams; fitting paintings to screens | | | `hibit_plate.py` | Hibit backgrounds: 480x270, one palette, majority downsample, paper-cut smoothing, shade maps | | | `map_bundle.py`, `map_nav.py` | map_bundle.v2 validation; collision, reachability and portals from data | | | `export_tiled.py`, `export_godot.py`, `export_ldtk.py` | Tiled 1.10 (re-render verified), Godot 4.3+ and LDtk 1.5.3 (parse level only) | | | `validate_chunks.py`, `validate_layout.py` | Room-chunk sockets; side-scroll jumps, slopes and decks | | | `build_scene_preview.py`, `references/runtime/map-runtime.mjs` | Single-file walkable HTML preview with a route check; JS collision that mirrors map_nav | | | `scene_layout_guide.py`, `validate_stage.py`, `extract_scene_lights.py`, `edit_locality_check.py` | HD-2D stage guide, aspect-robust battle layout, lights and atmosphere, variant locality | | | `build_motion_mask.py`, `scene_motion.py` | Masked motion on a still plate; GOP-aligned loops with decoded-seam QA | | generate2dmedia | `route_media.py` | `image`, `video`, `resolve`: API key first, then the local CLIs, then `no-route` | | | `media_providers.py` | The five API adapters (OpenAI, Gemini, xAI, BytePlus, fal.ai) behind one interface; `list` prints the models | | | `forge_doctor.py` | Capability check, configured keys (yes/no) and the route order; `--verify-route` | | | `cli_media.py` | Local Codex/Grok CLI image, edit and video routes; `resume`, `adopt --codex-thread`, `batch` | | | `generate_media.py`, `media_ledger.py` | One paid API call with a dry run, caps and receipts; ledger summary and settle | | codeart2d | `render_pixelspec.py`, `pixel_qa.py` | PixelSpec to exact-palette frames and clips; pixel-art QA | | | `svg_render.py`, `rig_animate.py` | Portable SVG `render`, `lint` and renderer `doctor`; SVG rigs with FK, two-bone IK and a ground constraint | | | `fx_build.py`, `fx_verify.mjs` | Six FX presets with hit events and the fx.v1 runtime; runtime checker | | | `autotile_build.py`, `layout_build.py`, `parallax_build.py`, `ambient_bake.py` | Seam-proven tilesets; playable top-down layouts; periodic parallax layers; ambient loops on a plate | | repository | `tools/install_skills.py`, `tools/vendor_sync.py`, `tools/check_links.py` | Guarded install and drift check; shared-module copies in sync; README/doc link check | ## Requirements | Need | Install | | --- | --- | | Every skill | Python 3.10+, `python -m pip install -r requirements.txt` (numpy>=1.26, Pillow>=10.1, scipy>=1.11; scipy is an accelerator with an identical numpy fallback) | | Video, sprite sets, packaging and scene loops | ffmpeg 5.1+ with libvpx-vp9 and libx264 on `PATH` | | Image and video generation (one of) | An API key for OpenAI, Gemini, xAI, BytePlus or fal.ai ([Setting API keys](#setting-api-keys)), or your own signed-in Codex CLI or Grok CLI | | codeart2d SVG art | `python -m pip install -r requirements-codeart.txt` (resvg-py>=0.5,<0.6), or the resvg-js CLI, or Chrome/Edge. PixelSpec sprites need nothing extra | | JS runtimes, `fx_verify.mjs`, scene preview checks | node 22 (optional); `build_scene_preview.py --verify` also uses playwright when present | | Hibit FX route A (optional, recommended) | node 18+ and your own clone of [pixelfx](https://github.com/patch-gg/pixelfx) (`git clone https://github.com/patch-gg/pixelfx`, then `--pixelfx ` or `PIXELFX_DIR`); without it hibit FX take the image route | | Contributors | `python -m pip install -r requirements-dev.txt`, then `python -m pytest -q` and `node --test "tests/js/*.test.mjs"` | ## Suggested prompts ### A character, start to finish ```text Use $generate2dsprite to make a master still of a fox ranger for a 2D platformer: orange fur, teal tunic, brown boots, side view facing right. Show me three takes. ``` ```text Use $video2dsprite to turn the approved fox master into idle, run, attack and hurt, pixel finish in 48x64 cells at 80 ms, and export it for Godot and Aseprite. ``` ```text Use $generate2dsprite and $video2dsprite with the hibit finish: a fox mage master as flat lineless art, then idle, walk, cast and hurt at 80 px, and a falling-star cast FX in her palette (pixelfx if I have it, else the image route). ``` ```text Use $generate2dsprite with the pixel-looks route: ref.png is a sprite whose look I like. Make my own swordsman as a 1x sprite in that look, then a mage and a skeleton knight beside him, and use $video2dsprite for idle, walk and attack sets on the same pixel grid. ``` ### Sprites and FX ```text Use $generate2dsprite to create a wizard spell bundle with cast, projectile and impact sprites. ``` ```text Use $video2dsprite with my existing side-view hero PNG as the master. Make a run loop and an attack, and report the routes and QC numbers. ``` ### Maps ```text Use $generate2dmap to create a small top-down village with a pond, roads to three exits, collision and a walkable HTML preview, then export it to Tiled. ``` ```text Use $generate2dmap to create an HD-2D battle plate for a harbour at night with lantern lights and moving water. ```
Whole-game prompts used for the showcase prototypes ```text use $generate2dsprite to create a 2D side-scrolling action game. It should include attack mechanics, map elements, and all the essential features. I would like you to design it, and all the necessary assets should be created using this skill. It needs to be an actually playable game, with a cyberpunk story setting. ``` ```text Use $generate2dsprite to create a 2D monster-collecting RPG. You only need to build one scene for now. It must include a starter monster selection mechanic, a battle screen, and all basic gameplay functions. I would like you to design all the elements and the story, and you can also decide which game engine to use. Use this skill to create any assets you need. The story should be set in the Sengoku period. ```
## Notes and limits - The scripts are not the creative brain, and numeric QA never approves anatomy or motion by itself: the agent looks at the review sheets, and you approve the master. - Image-to-video models drift on fast limbs and jumps. Expect retakes on run and jump; the gates and fix clauses exist for that, and the live record shows how many it took. - What is and is not proven is in [docs/known-limitations.md](./docs/known-limitations.md); live results are in [docs/validation-2026-10-06.md](./docs/validation-2026-10-06.md). - Engine and editor imports of the 0.4.0 exporters are not verified yet (see [Engine exports](#engine-exports)). - Pixel looks: an image-to-video clip is 720p, so a sprite of about 80x110 with a wide swing gets only 4 px a sprite pixel there and its dark shades flip more. The limits are in [references/pixel-looks.md](./skills/generate2dsprite/references/pixel-looks.md). ## Generated assets and licensing The MIT license below covers this repository's code and documentation. It does not cover what you generate with it. Images and videos from an image or video model are subject to that provider's terms; code-drawn art is produced from specs you or your agent write. Do not trace or prompt for characters or people you do not own. For commercial projects, use original characters or IP you control, and check each provider's terms. ## Third-party credits The optional pixel-FX route (`skills/generate2dsprite/scripts/fx_pixelfx.py`, route A for hibit games, and our recommendation when you can install it) runs [pixelfx](https://github.com/patch-gg/pixelfx) by Patch, a separate MIT-licensed project that you clone yourself; it is not bundled here. The pixelfx effects in the hibit showcase media are credited in [src/hibit/CREDITS-pixelfx.txt](./src/hibit/CREDITS-pixelfx.txt). pixelfx in turn credits Sprite Fusion's pixel-art VFX by Hugo Duprez (MIT) and Hollow Crown by rehan-remade (MIT). Every render writes `CREDITS.txt` with pixelfx's license and notice: keep it with the frames and credit pixelfx in your game. Details: [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md). ## Repository layout ```text agent-sprite-forge/ .claude-plugin/ plugin.json, marketplace.json (Claude Code) skills/ generate2dsprite/ SKILL.md, agents/openai.yaml, references/, scripts/ video2dsprite/ generate2dmap/ generate2dmedia/ codeart2d/ examples/ with every spec shown above shared/ canonical shared modules and JSON schemas (vendored into skills) tools/ install_skills.py, vendor_sync.py, check_links.py tests/ pytest and node suites, fixtures with provenance docs/ validation records, known limitations, audit src/ README media (src/v040: the 0.4 showcase; src/hibit: the hibit showcase; src/pixel-looks: the pixel-looks showcase) CHANGELOG.md ``` ## Star history Star History Chart ## License MIT. See [LICENSE](./LICENSE).