0x0funky/agent-sprite-forge

Agent Sprite Forge

Languages: English | 繁體中文 | 简体中文 | 日本語 | 한국어

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.

1. One approved master still Generated by the local Codex CLI (image_gen), take 1 of 3.

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.

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.

What's new · Quickstart · Routes and providers · Pipeline · Maps · Showcase · Tools

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:

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.	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.
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.	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.
• 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. The live record, weak points included: docs/validation-2026-10-06.md.

Quickstart

1. Install

Claude Code (plugin)

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

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). Without one, the agent uses your signed-in Codex or Grok CLI.

2. Make the master still

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.

3. Make the sprite set

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):

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 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, api-usage.md, provider-survey.md, 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) |

{
  "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

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 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 base

Dressed reference

3x3 prop pack

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 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 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.
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 A playable side-scroller prototype built around generated character, attack, map and gameplay assets.
Sengoku Era — JavaScript monster RPG A browser RPG prototype with generated characters, starter selection, map flow and battle UI. Play build	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

Enemy roster, including flyer and boss units

Tower lineup

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

Summons, enemies, pickups, HUD and objective flow

Level-up choices: summon unlocks, training, stats and recovery

• Assets/Survivors/Scenes/SummonSurvivors.unity as the playable scen