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 <folder> 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 (<skill-dir> is the installed video2dsprite folder):

python "<skill-dir>/scripts/sprite_set.py" plan --master art/aria-master/master.json --output-dir art/aria-set
python "<skill-dir>/scripts/sprite_set.py" run --plan art/aria-set/set_plan.json
python "<skill-dir>/scripts/sprite_set.py" review --plan art/aria-set/set_plan.json
python "<skill-dir>/scripts/sprite_set.py" accept --plan art/aria-set/set_plan.json --action run --take 2
python "<skill-dir>/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 "<generate2dmedia>/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