Skip to content

0x0funky/agent-sprite-forge / skills/generate2dsprite

generate2dsprite

Verified

Make game-ready 2D characters, creatures, props, icons and FX as master stills, sprite sheets or animation clips. Plan size, motion and finish; generate the art (image generation is the default, through generate2dmedia route_media.py - the API when a key is configured, else the local Codex or Grok CLI); approve one master still per character; then key, slice, register, scale, palette, QA and export frames for a game engine (Aseprite JSON, Godot SpriteFrames or Sprite3D). HD finish by default, pixel finish on request. Character animation is one image-to-video clip per action from the master (video2dsprite); sheets are for FX, icons and props. Use for sprites, masters, sheets, frame-by-frame animation and packaging frames from any source. Not for maps, tiles or backgrounds (generate2dmap), video clips (video2dsprite), code-drawn art (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).

FileKindSize
SKILL.mdskill md17.1 KB
agents/openai.yamlconfig529 B
references/action-recipes.mdmarkdown13.8 KB
references/animation-planning.mdmarkdown9.1 KB
references/character-animation.mdmarkdown3.9 KB
references/engine-export.mdmarkdown13.7 KB
references/frames-and-clips.mdmarkdown16.2 KB
references/hibit.mdmarkdown7.1 KB
references/master-still.mdmarkdown15.1 KB
references/modes.mdmarkdown6.1 KB
references/palette-and-pixels.mdmarkdown12.0 KB
references/pixel-looks.mdmarkdown20.5 KB
references/processing.mdmarkdown14.2 KB
references/prompt-rules.mdmarkdown9.8 KB
references/runtime-integration.mdmarkdown10.6 KB
references/schemas/common.schema.jsonconfig12.9 KB
references/schemas/host.schema.jsonconfig18.8 KB
references/schemas/sprite.schema.jsonconfig80.7 KB
references/video-handoff.mdmarkdown7.8 KB
scripts/assemble_frames.pyscript51.9 KB
scripts/build_animation_clips.pyscript73.9 KB
scripts/export_engine.pyscript65.1 KB
scripts/forge_core.pyscript86.4 KB
scripts/forge_hibit.pyscript18.8 KB
scripts/forge_index.pyscript24.8 KB
scripts/forge_matte.pyscript71.6 KB
scripts/forge_palette.pyscript70.2 KB
scripts/forge_pixelgrid.pyscript74.0 KB
scripts/fx_pixelfx.pyscript26.0 KB
scripts/generate2dsprite.pyscript135.7 KB
scripts/hibit_fx.pyscript15.8 KB
scripts/make_anchor_layout.pyscript7.3 KB
scripts/make_layout_guide.pyscript6.1 KB
scripts/master_still.pyscript88.0 KB
scripts/palette_tool.pyscript40.6 KB
scripts/pixel_look.pyscript64.9 KB
scripts/pixel_reduce.pyscript15.2 KB
scripts/plan_guide.pyscript32.6 KB
scripts/scale_frames.pyscript37.8 KB
scripts/sheet_qc.pyscript70.3 KB
---
name: generate2dsprite
description: Make game-ready 2D characters, creatures, props, icons and FX as master stills, sprite sheets or animation clips. Plan size, motion and finish; generate the art (image generation is the default, through generate2dmedia route_media.py - the API when a key is configured, else the local Codex or Grok CLI); approve one master still per character; then key, slice, register, scale, palette, QA and export frames for a game engine (Aseprite JSON, Godot SpriteFrames or Sprite3D). HD finish by default, pixel finish on request. Character animation is one image-to-video clip per action from the master (video2dsprite); sheets are for FX, icons and props. Use for sprites, masters, sheets, frame-by-frame animation and packaging frames from any source. Not for maps, tiles or backgrounds (generate2dmap), video clips (video2dsprite), code-drawn art (codeart2d, only on request) or calling an image or video API by itself (generate2dmedia).
---

# Generate 2D Sprite

Make the smallest asset bundle the game needs, at its real display size, camera and style.
Game logic (collision, damage, timing) stays independent of the art.

## Use when

- A character, creature, prop, item, icon or FX is needed as a master still, a sheet or clips.
- Frames already exist (generated, painted, code-drawn) and need clips, palettes or an engine export.

## Do not use when

- Maps, tiles, terrain, parallax or scene plates: [generate2dmap](../generate2dmap/SKILL.md).
- Animating a character: approve one master here, then [video2dsprite](../video2dsprite/SKILL.md) makes one clip per action ([video-handoff.md](references/video-handoff.md)).
- Code-drawn art the user asked for: [codeart2d](../codeart2d/SKILL.md). Only an API or CLI call: [generate2dmedia](../generate2dmedia/SKILL.md).

## Capability check (once per session)

Run `python "<skill-dir>/../generate2dmedia/scripts/forge_doctor.py" --host-tools <tools> --save <output>/doctor.json`, where `<tools>` lists the media tools in your own tool list (`image_gen`, `image_edit`, `image_to_video`) or `none`. Its `ROUTES` block shows which API keys are configured (yes or no), the local readiness and the resolved order. If `encoding.stdout` fails, set `PYTHONUTF8=1`.

## Art source

Image generation is the default art source for characters, creatures, props, icons and FX. Record it as `art_source` (`api`, `host_image`, `existing`, or `code` only on request) and name the route in your reply. A route the user names explicitly wins.

1. **API**, when a key is configured: OpenAI (`OPENAI_API_KEY`), Google Gemini (`GEMINI_API_KEY`), xAI (`XAI_API_KEY`), BytePlus Seedream (`ARK_API_KEY`) or fal.ai (`FAL_KEY`), in the environment or the user config file ([route-media.md](../generate2dmedia/references/route-media.md)). The configured key is the owner's consent, so there is no per-call question.
2. **Local**: your own image tool (Codex `image_gen`, Grok's native tool) when you have one, otherwise the user's signed-in Codex CLI, then Grok CLI.
3. **codeart2d** only when the user explicitly asks for code-drawn art, or when `route_media.py` prints `no-route` (exit 3). Then say "code-drawn, no image model".

Hibit FX are the one exception: `fx_pixelfx.py check` sends them to pixelfx when the user has it installed (route A, third-party code-drawn FX, credited and disclosed), else to the image route (route B). See [hibit.md](references/hibit.md#4-fx-route-a-pixelfx-or-route-b-image-route).

Every image goes through one command: `python "<skill-dir>/../generate2dmedia/scripts/route_media.py" image --prompt-file <txt> --reference <png> --size 1024x1024 --out-dir <new>`. It picks the route in that order and prints one JSON line with `route`, `artifact`, `sha256` and `estimateUsd`; `resolve --kind image` says which route would run. Existing art the user supplies is always welcome. Never claim a generation that did not happen; keep the prompt and contract and report a missing capability.

- **Finish:** HD is the default: full colour, clean alpha, one registration and a premultiplied area downscale to the game height. The pixel finish (one shared palette, binary alpha, no dither) is an option when the user asks for pixel art; the hibit finish (flat lineless art from the model, then one character palette, a majority-vote downscale and an outline colour taken from the image) when they want the hi-bit look ([hibit.md](references/hibit.md)). Never prompt an image model for a logical pixel grid; the pixel look comes from the finish.
- **Pixel looks (only on request):** when the user wants the characters themselves as classic small pixel sprites, `pixel_look.py` makes a real 1x sprite that follows a reference picture (a sprite the user likes: the look comes from that picture, never from words), makes every pose and view from that master on its own lattice so the build cannot change, and video2dsprite `pixel_motion.py` makes the motion ([pixel-looks.md](references/pixel-looks.md)). It is not a default and replaces nothing above; it is the one place where a model is asked for pixels, because the grid it draws is then measured and followed, never trusted.
- **Characters:** approve one master still per character, then animate it with video2dsprite: one image-to-video clip per action, all from that master (`sprite_set.py`). Keep every action's body height from the master's rest pose.
- **Sheets** are for FX, icons and props (and frames the user supplies), not for character animation.

## Master still (every character animation starts here)

One approved master still per character, then one image-to-video clip per action from it ([video2dsprite](../video2dsprite/SKILL.md)); sheets are for FX, icons and props. Wording: [prompt-rules.md](references/prompt-rules.md); commands, framing and `master.json`: [master-still.md](references/master-still.md).

1. Spec (`--spec <json>` and/or flags): `--name`, `--subject`, `--identity` (long and precise), `--facing left|right|front|back`, `--class hero|mob|boss|prop`, `--finish hd|pixel|hibit` (HD default; pixel or hibit only when asked; hibit makes the still flat and lineless), `--identity-ref` (FIRST image, copied exactly), `--style-ref` (SECOND: an approved peer sprite, style and framing only), `--key` (default `#FF00FF`; green or blue for purple and pink designs).
2. Generate: `python "<skill-dir>/scripts/master_still.py" generate --spec <json> --takes 3 --output-dir <new>`. Each take goes through generate2dmedia `route_media.py` (API key first, then the local daemon); `takes.png` shows them side by side. Exit 3 means no route: say so; codeart2d is the fallback ("code-drawn, no image model"). With the host's own image tool: run `master_still.py prompt` and attach the listed references in that order.
3. Choose by looking: identity, facing, nothing touching an edge, no text.
4. Fix a near-miss by edit, never by re-roll: `master_still.py edit --run <dir> --take N --change "<one change>" --output-dir <new>` (or `--master <dir>`).
5. Approve: `master_still.py approve --run <dir> --take N --output-dir <new>` (a still from elsewhere: `--still <png> --route <what made it>`). It keys the still, crops it with a 6 px margin, LANCZOS-scales it to the class framing on 1024x1024 (hero 788 px tall, top margin 138 px) and writes `master.png` (opaque, pure key), `master_rgba.png` and `master.json` (`generate2dsprite.master.v1`).
6. Motion steps read `master.json` (`identity_recap`, `facing`, `finish`, `class`, `framing`, `key`, `files`, `transform`, `route`) and never re-measure the still; every clip prompt starts with "The same <identity_recap>".

Report the route from `master.json` `route`. A `FORGE_ROUTE_MEDIA_FAKE` warning means the image is not a real generation.

## Host notes

- **Codex:** `image_gen` is your own image tool; with no configured key use it and look at results with `view_image`. An image this session made that is not in the project: `python "<skill-dir>/../generate2dmedia/scripts/cli_media.py" adopt --codex-thread <thread-id> --output-dir <new>`, then process `generated.png`. codeart2d and generate2dmedia are explicit-only: open their SKILL.md when this one routes there.
- **Claude Code:** no built-in image generator: `route_media.py` takes the API or the local CLIs. Look at every PNG you make with Read; run tools with Bash; `<skill-dir>` is `${CLAUDE_SKILL_DIR}`.
- **Grok:** its native image and video tools are your own tools; use their real schema.

## Commands

Run each tool as one line from the user's project root: `python "<skill-dir>/scripts/<tool>.py" ...`. `<skill-dir>` is this skill's folder; sibling skills sit beside it (`<skill-dir>/../video2dsprite`). Keep inputs and outputs inside the project. Every tool writes a new `--output-dir`: it refuses an existing one, stages beside it and publishes only after its checks (`--strict-qc` / `--strict` publish nothing on failure). Success prints one JSON line; errors print `error: ...` and exit 1 (nothing usable is published); usage errors exit 2; a result published for inspection with QA status `fail` exits 4. `master_still.py generate` and `edit` exit 4 when every take failed (the run folder is kept for diagnosis) and take `--progress-file <jsonl>` (or `FORGE_PROGRESS_FILE`): one JSON line per stage for a host, never on stdout. Needs Python 3.10+, numpy and Pillow (scipy recommended). `--help` lists every flag. A host lists everything the skills made under a folder with `python "<skill-dir>/scripts/forge_index.py" scan <dir>` (one `forge.asset_index.v1` JSON line: masters, sprite sets (each action's chosen and accepted take, and the package and review status of the chosen take only), FX, plates, maps; `references/schemas/host.schema.json`).

## Plan the asset

Record identity and reference, camera and facing, style, game display size, finish (HD by default, pixel on request), action list and phases, loop or one-shot, motion envelope, shared root and output format. Keep one accepted master and one source-to-display scale per character; mobs are no taller than the hero unless planned. A grid is not smoothness: pose spacing, timing, the loop seam and ground contact matter more. Poses, NEAR/FAR legs and timing: [animation-planning.md](references/animation-planning.md).

- Alpha: `native_alpha` keeps real transparency (a painted checkerboard is not alpha); `chroma_key` uses flat magenta only when the subject has none; `opaque` keeps whole images (`assemble_frames.py`).
- Sampling: `lanczos` or a premultiplied area resize for generated art; `nearest` only for a verified pixel grid. A high-resolution pixel-like painting is not clean 32 px art.
- A shared root is not a per-frame alpha-bbox bottom: keep intentional flight, jumps, bob and recoil.

## Generate (image routes)

Write the prompt yourself ([prompt-rules.md](references/prompt-rules.md); grids, phases and presets in [action-recipes.md](references/action-recipes.md)). Attach references through `--reference` (or your tool's real image input); a path in prose is not a reference. Keep the accepted master in every generation and describe absolute phases, not chained edits; a fix is an edit of the approved still that names the only change. Generate one action family at a time and keep wide slashes, trails and projectiles out of the body sheet. Verify the actual route, model and returned size; never claim them from the prompt.

## Pipeline

Sheets (FX, icons, props): `sheet_qc.py spill` on the raw sheet, then `generate2dsprite.py process`, then `sheet_qc.py frames`, then `scale_frames.py`, then `build_animation_clips.py`, then `export_engine.py`. Character actions come back from video2dsprite as packaged clips.

| Need | Route |
|---|---|
| Plan a sheet for an image tool (aspect, grid, guide, prompt) | `plan_guide.py --frames N --cycle run --output-dir <new>`; attach `guide.png`, paste `prompt.txt`. Fixed scale and feet line: `make_anchor_layout.py`; empty safe frame: `make_layout_guide.py` |
| Check a raw sheet before slicing | `sheet_qc.py spill --input <sheet> --rows R --cols C --output-dir <new>`; crossing parts mean regenerate with more margin or slice by ownership, never a largest-component filter |
| Key, slice and register a sheet | `generate2dsprite.py process --input <sheet> --target asset --mode <mode> --rows R --cols C --output-dir <new> --strict-qc` (geometry v2; [processing.md](references/processing.md)) |
| Pixel art drawn at M source px per art px | `process --resampler nearest --logical-pixel M --pixel-scale N` (whole scales only) |
| Jumps, bob or recoil on one registration point | `process --scale-strategy registered` (or `--anchor-px X,Y`) |
| One character's scale across actions | `process --write-scale-profile <p.json>` on the grounded reference, then `--scale-profile <p.json> --max-profile-scale-drift 0.08` |
| Canvas does not divide into the grid; other row order | `process --grid-rounding nearest` or `--pad-to-grid`; `--direction-order down,up,left,right` ([modes.md](references/modes.md)) |
| Identity, NEAR/FAR alternation, drift, baselines | `sheet_qc.py frames --sheet <sheet> --rows R --cols C --cycle run --output-dir <new>`; a duplicated half-cycle means regenerate the second half. On code-drawn frames (`art_source=code`) `identity_residual` and `torso_drift` are advisory |
| Game size on one canvas and root, never clamped | `scale_frames.py --frames <pngs> --root-lock torso-x --row-baseline --emit-clips --ticks N --output-dir <new>`; later actions add `--profile <first>/scale-frames.json --action-padding L,T,R,B` |
| Clips with timing, events, transitions | `build_animation_clips.py --manifest clips.json --output-dir <new>`; read the lints and `review/` ([frames-and-clips.md](references/frames-and-clips.md)) |
| Whole frames or a scene loop (no keying) | `assemble_frames.py` (`--key chroma`, `--slice ownership`; `--loop-overlap K --ambient` for ambient loops only) |
| Shared palette, locks, variants, flicker (pixel finish) | `palette_tool.py build`, `apply`, `lock`, `quantize-seq`, `variants`, `luts`; strict logical grid: `pixel_reduce.py` ([palette-and-pixels.md](references/palette-and-pixels.md)) |
| A character as a small real pixel sprite (a pixel look, only on request) | `pixel_look.py ask-master`, the image route, `pixel_look.py master` (the user accepts the manner, then the master); every further character beside that master with `ask-cast` and `cast`; a weapon or a pose with `ask-pose` and `pose`, a side or back view with `ask-view` and `view` (both made from the master, never as pictures of their own); `lineup` before any motion is shown; motion with video2dsprite `pixel_motion.py` ([pixel-looks.md](references/pixel-looks.md)) |
| Engine export | `export_engine.py --clips <animation-clips.json> --target all --output-dir <new>`; Sprite3D: `--target godot-sprite3d --world-height <units>` ([engine-export.md](references/engine-export.md)) |
| Play clips in a game (gait, hit-stop, transitions) | [runtime-integration.md](references/runtime-integration.md) |
| Code-drawn sprites, rigs or FX, only on request | codeart2d `render_pixelspec.py`, `rig_animate.py` or `fx_build.py` with `--build-clips` (never `process`), then `export_engine.py`; disclose them as code-drawn |
| FX for a hibit game | `fx_pixelfx.py check` picks the route (a route the user names wins). A, pixelfx installed (recommended): `fx_pixelfx.py render --pixelfx <checkout> --id <effect> --ramp ... --snap <palette.json>`, [pixelfx](https://github.com/patch-gg/pixelfx) by Patch (MIT, a separate project the user clones), ship `CREDITS.txt` and disclose as code-drawn by pixelfx. B, otherwise: a 2x2 FX sheet from the image route, `process --scale-strategy registered --cell-size 512`, then `hibit_fx.py pixelize --palette <palette.json>` ([hibit.md](references/hibit.md)) |

## Acceptance

- Review at game size: silhouette and identity, contact and flight, loop seam or one-shot recovery, alpha over light and dark, extremities, scale across actions, root and collider.
- Quote numbers for quality claims: `pipeline-meta.json` `matte.qa` (a `key_ring_spill` warning: add `--despill-radius 1` or `--key-quality soft`), `sheet-qc.json`, the clip builder's lints. Numeric QC finds symptoms; it never approves anatomy or motion.
- Report every WARN or FAIL check verbatim (id, value, threshold, files) from each published QA envelope; never say "all checks passed" when any published envelope has a warn.
- Deliver accepted source art, runtime frames or clips, preview, prompt and provenance (route, model, `estimateUsd`), QA and remaining limits. Keep the last accepted bundle when revising.

## References

[processing.md](references/processing.md) (process flags, legacy switches), [modes.md](references/modes.md), [prompt-rules.md](references/prompt-rules.md), [action-recipes.md](references/action-recipes.md), [character-animation.md](references/character-animation.md) (animation index), [frames-and-clips.md](references/frames-and-clips.md), [palette-and-pixels.md](references/palette-and-pixels.md), [hibit.md](references/hibit.md) (hi-bit finish, plates, FX routes A pixelfx and B image), [pixel-looks.md](references/pixel-looks.md) (pixel looks: small real pixel sprites that follow a reference, and their motion), [engine-export.md](references/engine-export.md), [runtime-integration.md](references/runtime-integration.md), [video-handoff.md](references/video-handoff.md); data contracts in `references/schemas/sprite.schema.json`.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall