System purpose
Agent Sprite Forge is a set of 2D game asset skills for Claude Code, Codex, and Grok. Its character animation workflow establishes appearance with one approved master still, generates one video per action, then processes keying, registration, loops, retiming, and packaging.
| Input | Processing | Output |
|---|---|---|
| Character description, references, or an existing master | Generate candidates, edit locally, approve by inspection | Master images and master.json |
| Approved master and action list | Per-action videos, QC, keying, registration, and timing | Frames, loops, or one-shot actions |
| Finished frames and selected timing | HD or pixel finishing, packaging, and decoding checks | PNG atlas, WebM, packed MP4, and animation.json |
| Map specification and art assets | Collision, navigation, and reachability checks | Map data, previews, and exports |
Implement game logic separately. Generated videos do not determine collision, damage, character movement, or state changes.
Installation and checks
- Not completed:
Python 3.10+ is installed, and
pythonpoints to that version. - Not completed:
Git and the Claude Code or Codex host you use are installed.
- Not completed:
Animation workflows have ffmpeg 5.1+ with the
libvpx-vp9andlibx264encoders available on PATH. - Not completed:
A media route is available through your API account, a signed-in local CLI, or existing assets.
- Not completed:
Character display size, facing, HD/pixel finish, and output target have been decided.
For Claude Code, use the plugin installation commands in the official README:
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"Install Codex skills from a clean source checkout. The direct CLI examples later in this guide also run from this repository root.
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
python tools/install_skills.py --check --host codexCodex defaults to ~/.codex/skills, or the skills directory under CODEX_HOME when set. Use --host agents to install into ~/.agents/skills. The installer backs up existing copies and writes a SHA-256 manifest.
Start a new agent session to load the skills, then check media routes and video tools:
python skills/generate2dmedia/scripts/forge_doctor.py --no-exec --json
python skills/generate2dmedia/scripts/route_media.py resolve --kind image
python skills/generate2dmedia/scripts/route_media.py resolve --kind video
python skills/video2dsprite/scripts/video2dsprite.py doctor--no-exec starts no external commands, so some capabilities can remain UNKNOWN. Resolving a route does not prove successful generation with the account. forge_doctor.py --verify-route with --execute consumes one quota call and is not a read-only check.
Core capabilities
Masters and assets
$generate2dsprite
Create character masters and asset specifications
Generate, edit, and approve character masters, and process prop, icon, and FX sheets. Character actions go to video2dsprite. HD is the default finish.
Character animation
$video2dsprite
Turn a master into action videos and frames
Use the same master for each action, then check quality, key, register, loop or retime, finish, and package. It also processes user-supplied videos.
Maps and scenes
$generate2dmap
Build scenes and playable map data
Process tiles, props, parallax, and HD-2D scenes, with data defining collision, spawns, and exits. Reachability checks do not verify whether collision matches the picture.
Media routing
$generate2dmedia
Choose generation services and record calls
Route image and video requests, check capabilities, and save job records and cost estimates. Other skills handle asset specifications and quality review.
Code art
$codeart2d
Specification-driven pixels, SVG, and effects
Provides PixelSpec, rig animation, procedural effects, and tile tools. Use only when explicitly requested or no generation route is available, within its style and size limits.
Character animation proceeds through the master, candidate videos, frames, and packages. QC measurements can flag scale or border problems; identity and motion still need visual inspection.
| Stage | Tool | Checks |
|---|---|---|
| Master | master_still.py | Appearance, facing, borders, and approval record |
| Action candidates | sprite_set.py | Master consistency, action list, retries, and fix clauses |
| Keying and registration | video2dsprite.py, register_clip.py | Alpha edges, key spill, fixed scale, and anchors |
| Loops or retiming | gait_loop.py, retime.py | Seams, foot contact, impact events, and hold duration |
| Finishing | finish_frames.py | Shared character scale, color lock, and HD or pixel output |
| Packaging | engine_export.py | animation.json, atlas, videos, and decoding checks |
Operating rules
Master approval and local edits
Approve one master per character. For a near-miss, name a single change with edit to avoid changing the weapon, outfit, or face during a new generation. Other actions reuse the master's identity description and scale.
Action boundaries and game logic
Use one video per action. Do not complete a walk loop by playing it backward or reverse an attack recovery. The game controls movement, damage, and event triggers.
Shared scale and keying settings
Share the master scale and keying settings across a character's actions. Do not resize each frame to its own alpha bounds. When design colors approach the background color, choose another key or protect those colors.
Measurements and visual review
Open contact sheets, finished frames, and the cast lineup. Inspect faces, weapons, facing, contact, and edges over light and dark backgrounds. Preserve each WARN or FAIL; passing numbers do not approve the art.
Automatic media routing tries APIs with configured keys before signed-in local CLIs. The project treats a configured key as permission to call the API and does not ask again for each generation. Check the route and spending settings before starting.
| Route | Scope | Operating limit |
|---|---|---|
| API | Configured OpenAI, Google Gemini, xAI, BytePlus, and fal.ai routes | Capabilities depend on the service and model; an explicitly selected route takes priority |
| Local CLI | Codex/Grok images; Grok image-to-video | Still consumes subscription quota; signing in does not provide an API key |
| Code art | Explicit request or a no-route result | Must not silently replace requested generated assets |
The project records calls in .forge/ledger.jsonl, and each output includes job.json. There are no default spending or quota caps. Set --budget-usd, --max-calls, or FORGE_MAX_PAID_REQUESTS explicitly, and use FORGE_SESSION_IMAGES/FORGE_SESSION_VIDEOS for quota caps by kind.
--max-takes limits candidates per action per round, not project spending. The estimate table is not a live bill. When no verified price is available, --budget-usd can refuse a route, so do not assume the same budget check works for every provider.
Worked example
The example creates idle, walk, and attack actions for Aria, an original swordswoman facing right in side view, with a teal cloak and red scarf. These commands are for the reader to execute; no assets were generated during this review. All paths start at the cloned repository root.
Set example caps for a new project before generating the master. These are operating examples, and existing ledger records also affect the remaining calls.
export FORGE_MAX_PAID_REQUESTS=4
export FORGE_SESSION_IMAGES=1
export FORGE_SESSION_VIDEOS=3
python skills/generate2dsprite/scripts/master_still.py generate \
--name aria --subject "a young swordswoman, full body" \
--identity "short dark hair, teal cloak, red scarf, one steel sword" \
--facing right --class hero --finish hd --takes 1 \
--output-dir art/aria-takesRead the generation result JSON and open the successful candidate's takes[*].artifact path to inspect identity, facing, and borders. The script creates takes.png only when at least 2 candidates succeed; this single-candidate example does not produce it. Approve the master after the candidate meets the requirements:
python skills/generate2dsprite/scripts/master_still.py approve \
--run art/aria-takes --take 1 --output-dir art/aria-masterApproval writes master.png, master_rgba.png, and master.json. After creating the action plan, read the prompts and action settings in set_plan.json before running generation.
python skills/video2dsprite/scripts/sprite_set.py plan \
--master art/aria-master/master.json --output-dir art/aria-set \
--actions idle,walk,attack --finish hd --target-height 256 \
--max-takes 1 --jobs 1 --formats png,webm,packed
python skills/video2dsprite/scripts/sprite_set.py run --plan art/aria-set/set_plan.json
python skills/video2dsprite/scripts/sprite_set.py review --plan art/aria-set/set_plan.jsonInspect each action's sheet, finished frames, and lineup under review/. The example allows one candidate per action and one generation job at a time. On failure, read the QC and spending records before increasing retries.
Run accept for each action only after inspecting its frames and deciding it is usable. This example assumes the first candidate for each action has passed visual review.
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action idle --take 1
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action walk --take 1
python skills/video2dsprite/scripts/sprite_set.py accept --plan art/aria-set/set_plan.json --action attack --take 1
python skills/video2dsprite/scripts/sprite_set.py report --plan art/aria-set/set_plan.json
python skills/generate2dmedia/scripts/media_ledger.py summaryreport lists routes, candidates, QC, loops, timing, and package paths. Running the same plan again reuses existing candidate videos. To make a correction, specify the problem with retake, check the spending caps, then rerun.
The report's actions[*].outputs.package paths are relative to the set root; the corresponding directory contains verify-qa.json only after video decoding verification passes. If you select another candidate or a partial window, run run after approval to complete finishing and packaging. Use a new report path when repeating verification to preserve the existing record.
Limits and failure handling
| Problem | Effect | Correction |
|---|---|---|
| Fast limbs, jumps, or unfamiliar outfits cause identity drift | Changed weapon shape, hidden face, or altered scale | Compare master and candidate, then request a local edit or retake |
| Key color is close to character colors | Keying removes clothing or leaves spill | Change the key, protect design colors, and inspect over light and dark backgrounds |
| Hands or feet touch the video border | Motion has already been cropped | Regenerate with more motion space; padding cannot recover missing picture content |
| Last frame or loop does not match the starting pose | Transition jumps or walk seams | Check last-frame support, select a loop, and play it |
| Output directory already exists | Tool refuses to write | Use a new directory and preserve the previous approved delivery |
The video packages from sprite_set.py use animation.json, while generate2dsprite's export_engine.py --clips requires a different animation-clips.json contract. Do not pass the former directly to the latter. Before Godot or Aseprite delivery, create compatible clip data using the frames-and-clips documentation, export, and test in the actual editor.
Official development and measurements mainly used Windows; macOS/Linux have not received the same verification. Numeric QA does not approve anatomy, character identity, or motion quality, and tool determinism is scoped to the same build environment.
Next steps
| Next requirement | Workflow | Acceptance checks |
|---|---|---|
| Add run, jump, or hurt | Create more action plans from the same master | Scale across actions, foot contact, and state transitions |
| Pixel style | Select pixel finishing, a shared palette, and fixed cells | Alpha, outlines, pixel grid, and loops |
| Playable map | Use generate2dmap data, navigation, and previews | Collision against picture, reachability, and exits |
| Engine delivery | Build the compatible clip contract and use its exporter | Actual editor import, events, and runtime playback |
Check skill responsibilities in the official README, and adjust actions and timing with the sprite-set documentation. Before delivery, check the known limitations and preserve the reproducible plan, source assets, and QA.