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

references/engine-export.md

View on GitHub
# Engine export and runtime playback

`scripts/export_engine.py` turns built clips (`animation-clips.json` from `build_animation_clips.py`, schema v1 or v2) into engine files: an Aseprite-style JSON atlas, Godot 4 SpriteFrames, and a Godot Sprite3D package. It never changes pixels, timing or the anchor; it only lays them out for each engine and proves the layout by reading it back.

> **Not verified in editors.** These exports have not been imported into Aseprite, Godot 4, Phaser, PixiJS or Unity by this skill. `export_engine.py` proves parse-level round trips only (see QA below). Import once by hand in each target engine and check the anchor, timing and loops before calling a pipeline compatible.

## Commands

Run from the project root. Outputs go to a new directory inside the project; an existing directory is refused.

```bash
python "<skill-dir>/scripts/export_engine.py" --clips out/hero-clips/animation-clips.json --target all --output-dir out/hero-engine
python "<skill-dir>/scripts/export_engine.py" --clips out/hero-clips/animation-clips.json --target aseprite-json --output-dir out/hero-aseprite --sampling nearest
python "<skill-dir>/scripts/export_engine.py" --clips out/hero-clips/animation-clips.json --target godot-spriteframes --output-dir out/hero-godot --godot-fps 12
python "<skill-dir>/scripts/export_engine.py" --clips out/hero-clips/animation-clips.json --target godot-sprite3d --output-dir out/hero-3d --world-height 1.7 --billboard fixed-y
```

In Claude Code, `<skill-dir>` is `${CLAUDE_SKILL_DIR}`. On success the tool prints one JSON line with `status`, `output`, `metadata` (the `engine-export.json` path), `targets`, `clips`, `frames` and `pages`. Errors print `error: ...` and exit 1 (a mistyped option exits 2 with argparse's usage line), and nothing is published.

Export the **built** manifest. A clips input manifest (`clips.json`) is refused with a pointer to `build_animation_clips.py`, which resolves names, ticks and pingpong into explicit frames and integer milliseconds first.

| Option | Default | Meaning |
|---|---|---|
| `--target` | `all` | `aseprite-json`, `godot-spriteframes`, `godot-sprite3d` or `all` |
| `--name` | output folder name | base name of the files (letters, digits, `-`, `_`) |
| `--max-atlas-size` | 4096 | largest atlas side; whole clips move to extra pages |
| `--padding` / `--extrude` | 2 / 1 | transparent gap between cells / replicated edge pixels around each frame |
| `--sampling` | `auto` | `nearest` or `linear`; auto reads the manifest `sampling` or `pixel_art`, else linear |
| `--godot-fps` | `auto` | Godot animation speed; auto uses a clip's ticks when it has them, else its shortest frame |
| `--world-height` / `--pixel-size` | pixel size 0.01 | Sprite3D scale: Godot units for the subject height, or the pixel size itself |
| `--subject-height-px`, `--reference-clip` | measured | subject height used for `--world-height` (else `body_height_px`, else the idle clip's median visible height). Only `godot-sprite3d` and `--world-height` need it: faint FX (nothing above alpha 32) exported to the atlas targets get no `scale` block, and the mapping table uses `--pixel-size` or 0.01 |
| `--billboard` | `enabled` | Sprite3D billboard: `enabled`, `fixed-y` or `disabled` |
| `--ppu`, `--camera-pitch-deg` | 1 / pixel size, none | fill the Unity and pitch-compensation rows of the mapping table |

## What each target writes

| Target | Files | Notes |
|---|---|---|
| `aseprite-json` | `aseprite/<name>.json`, `aseprite/<name>.png` | JSON array atlas. Frames are named `"0"`, `"1"`, ... (Aseprite's `{frame}` naming, which Phaser's `createFromAseprite` expects). One `frameTags` entry per clip (`direction` forward, `repeat` `"1"` for one-shot clips), tag `data` holds the events as JSON, one `anchor` slice carries the pivot, and a top-level `animations` map lists each clip's frame names for PixiJS. |
| `godot-spriteframes` | `godot/<name>.tres`, `godot/<name>.tscn`, `godot/<name>-atlas-NN.png` | SpriteFrames over AtlasTexture regions (`filter_clip` on) and an AnimatedSprite2D scene with the anchor offset and texture filter. |
| `godot-sprite3d` | `godot-sprite3d/<name>.tres`, `.tscn`, `frames/*.png`, `action-<clip>.json`, `bundle.json` | AnimatedSprite3D over one texture per frame (no atlas, so mipmaps cannot bleed between cells), plus `generate2dsprite.godot_sprite3d.v1` contracts and a bundle whose paths are all relative. |
| always | `engine-export.json` | the files with sha256, per-clip frames, durations, events, `transition_hints`, keys and Godot timing, the mapping table and the QA envelope |

Atlas pages are at most 4096 px. Identical frames share one cell. A clip never spans two pages (an Aseprite tag addresses one image), so a clip whose distinct frames do not fit one page is refused by `aseprite-json` and `godot-spriteframes`: split it or export smaller frames. `godot-sprite3d` draws one texture per frame, so an export of that target alone plans no atlas (`atlas.pages` is empty and the clips carry no `page`) and has no page limit. Frames are not trimmed or rotated.

Text paths inside the export are relative: Godot resolves a relative `ext_resource` path against the `.tres`/`.tscn` that names it (Godot rewrites it to `res://` when it saves the resource again), and every Sprite3D contract lists its frames relative to itself (finding S19). Move the whole output folder into the engine project; nothing points back at the source bundle.

### Godot timing

Godot shows a frame for `relative_duration / speed` seconds, so the export writes `relative_duration = ms x speed / 1000`:

- `--godot-fps N`: speed N for every clip.
- auto, a clip with integer `ticks` at `tick_hz` (consistent with its ms): speed = tick rate, relative durations = ticks (exact 60 Hz timing). Ticks are authored positions: a pingpong clip's ticks are mapped onto its played frames (authored 0 1 2 plays 0 1 2 1).
- auto, otherwise: speed = 1000 / shortest frame ms, so the shortest frame is 1.0 and an evenly timed clip is all 1.0.

The round trip requires the recovered milliseconds to equal the source to 1e-6 ms (1 ms for tick-timed clips, the builder's tick rounding). SpriteFrames cannot carry events: read them from `engine-export.json` (`clips.<name>.events_ms`) or the Aseprite tag data.

### Positions, events and transition hints

Built clips list the **played** timeline: `frames` and `duration_ms` of a pingpong clip arrive expanded (authored 0 1 2 3 plays 0 1 2 3 2 1) and `authored_frames` keeps the authored order. The positions follow `sprite.schema.json` builtClip:

- `events_ms[].at_ms` is authoritative. `position` is the played frame (the index into `frames`): taken when the built clip gives it, otherwise found from `at_ms` on the duration edges, and refused when the two disagree. `at` is the **authored** position, so an event authored once fires on every played occurrence (a pingpong `step_l` at authored 1 fires at played frames 1 and 3).
- `engine-export.json` writes each event with `at_ms`, `at` and `position`; the Aseprite tag data and the Sprite3D contracts place it on the played frame (`frame` = tag `from` + `position`). Event names follow `common/eventName` (`custom:<name>` for anything else).
- `ticks`, `keys` and `entry_frame` stay authored positions (with `keys_ms`, `entry_ms` and `hitstop_ms` beside them); `authored_frames` comes along so a reader can map them.
- Transition hints are read from `transition_hints`; a clip without them falls back to legacy `transitions` items that name a target clip with `to` (built clips keep `transitions` for the frame-to-frame metrics). They are written as `transition_hints`, and each must name a clip of the manifest and enter it at one of its authored positions.

## Anchor mapping table

The clips share one anchor `anchor_px = (ax, ay)` in a `w x h` frame (continuous pixel coordinates, y down; often the ground contact). `engine-export.json` carries these values for the exported sprite under `mapping`.

| Engine | Setting | Value |
|---|---|---|
| Godot AnimatedSprite2D | `centered = false`, `offset` | `(-ax, -ay)` (written to the `.tscn`) |
| Godot AnimatedSprite2D | `centered = true`, `offset` | `(w/2 - ax, h/2 - ay)` |
| Godot Sprite3D / AnimatedSprite3D | `centered = true`, `offset` (+Y up) | `(w/2 - ax, ay - h/2)` |
| Godot Sprite3D | `pixel_size` | `world_height / subject_height_px`; Godot's default is 0.01 |
| Unity | Sprite pivot (normalized, origin bottom-left) | `(ax / w, 1 - ay / h)` |
| Unity | Pixels Per Unit | `1 / pixel_size` (100 at Godot's default); pixel art often uses its tile size |
| Phaser | `sprite.setOrigin(x, y)` | `(ax / w, ay / h)` |
| PixiJS | `sprite.anchor.set(x, y)` | `(ax / w, ay / h)` |
| Aseprite | slice `anchor` pivot | `(round(ax), round(ay))` half up; the exact value is in the slice `data` |
| Yaw-only (fixed-y) billboard under a camera pitched by p | vertical scale about the anchor | `1 / cos(p)` (`--camera-pitch-deg` fills an example) |

Texture filter: `nearest` for pixel art, `linear` for painted art.

| Engine | nearest | linear |
|---|---|---|
| Godot 2D (`texture_filter`) | 1 | 2 |
| Godot 3D (`texture_filter`) | 0 | 3 (linear with mipmaps; per-frame textures, so no cell bleeding) |
| Unity | Filter Mode Point, Compression None | Bilinear |
| Phaser | game config `pixelArt: true` | default |
| PixiJS | `scaleMode` nearest | linear |

## Manual import checklist

- **Godot 4**: copy `godot/` or `godot-sprite3d/` into the project and open the `.tscn`. For pixel art set the PNG import to Lossless without mipmaps (Godot may switch textures used in 3D to VRAM compression, which blurs pixels). Check the feet on the node origin and `autoplay`.
- **Phaser**: `this.load.aseprite('hero', 'hero.png', 'hero.json')`, then `this.anims.createFromAseprite('hero')` and `sprite.setOrigin(...)` from the table. Check that one-shot clips stop and per-frame durations hold.
- **PixiJS**: load `hero.json`; `sheet.animations.<clip>` lists the textures; give an AnimatedSprite per-frame `time` from `frames[i].duration`.
- **Unity**: import the PNG as a Sprite (Multiple) with an Aseprite-JSON importer or an editor script that reads `frames[].frame`; set pivot and Pixels Per Unit from the table.

Record what you imported and in which engine version before claiming support in a README.

## Runtime playback

The video2dsprite skill ships DOM-free runtime helpers in its `references/runtime/forge-runtime.mjs` (with the packed-alpha WebGL compositor beside it). They read `engine-export.json` clips, `animation-clips.json` clips and video `animation.json` 2.0/3.0 alike (`normalizeClip`), and work for sprite sheets too.

- **Distance-driven walk.** Drive the gait phase from distance actually travelled, never from the wall clock: feed the position after collision to `TravelMeter`, then `walkPlayback(clip, meter.distance, speed)` or `gaitFrame(distance, stride, frames)`. Both share one phase, so a blocked actor keeps its pose and a video walk and a sheet walk stay in step. The travel per loop is `stride_world_units` (sprite clips, per clip cycle) or `strideWorldUnits x cycles` (video). Enter on `entry_frame` with `phaseOffset(distance, loopDistance, entryPhase(clip))`.
- **Transitions.** `transitionHint(clip, to)` gives the entry frame and dissolve time from the clip's `transition_hints` (legacy `transitions` items with `to` still count). `ditherDissolve(progress, x, y)` keeps the outgoing pose's pixel at sprite-local `(x, y)` while true; draw the incoming pose underneath (`ditherDissolvePixels` does this on pixel arrays). Mode `premultiplied` uses `premultipliedMix`.
- **Hit-stop.** One `HitStopClock` per entity: `hitStop(clip.hitstop_ticks)` at the hit event freezes the action clock while the world clock keeps shaking and spawning particles. Longer requests win; they never stack.
- **Time-warp onto hits.** `mapActionTime(clip, {durationMs, impactTimesMs}, elapsedMs)` stretches the clip so its impact frame lands on every gameplay hit (multi-hit attacks included) and returns the frame and playback rate.
- **Fixed step and events.** `FixedStepLoop` runs the simulation at 60 Hz with an interpolation `alpha` for rendering and drops a long stall instead of spiralling; `frameAt(clip, t)` picks frames from integer durations that sum exactly; `eventsCrossed(clip, previousMs, nowMs)` fires each event once per crossing.
- **Integer-scale snapping.** For pixel art pick `integerScale(available, frameHeight)` and place frames with `anchoredRect(source, x, y, scale, {snap: true})`; never draw at fractional scales.
- **Sampling.** Use nearest sampling for pixel art (`texture_filter`, `imageSmoothingEnabled = false`, Phaser `pixelArt`) and linear for painted art, as recorded in `engine-export.json` `sampling`.

Pitfalls seen in earlier prototypes: choosing walk frames from elapsed time (feet slide, and the walk keeps playing against a wall); drawing pixel art at fractional sizes (uneven pixel widths); hard-coded foot offsets instead of the anchor; a sine bob added on top of drawn walk frames; splitting a sheet by a guessed frame count instead of the manifest.

## QA and what it does not prove

Before publishing, every written file is parsed back: Aseprite frames are cropped from the atlas and compared with the source frames (exact RGBA), durations, tags, events and the pivot are compared, the SpriteFrames `.tres` and `.tscn` are parsed and their textures, regions, loops and recovered milliseconds checked, and every Sprite3D frame path is resolved relative to its contract with its sha256. Any mismatch publishes nothing. `engine-export.json` records the checks in a QA envelope (`method`, `notProven`, inputs and outputs with sha256). A fractional anchor gives status `warn` (the Aseprite pivot is rounded).

Not proven: imports and playback in Aseprite, Godot, Phaser, PixiJS and Unity; engine import settings (filter, compression, mipmaps are not written); animation quality and timing feel.
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: 197kUpdated Claude CodeCodexVerifiedInstall