Sprite Gen

Sprite Gen

sprite-gen builds generic game sprite atlases with a component-row pipeline:

sprite-request.json -> layout guides + prompts -> image-gen state rows
-> chroma alpha -> connected components -> transparent cells
-> sprite-sheet-alpha.png + manifest.json.frame_layout

Use only the component-row pipeline. Do not treat one-shot master sheets, fixed-grid atlas cutting, local drawing, or static fallback as a successful sprite result.

Script Map

The skill uses scripts as explicit pipeline commands, not as hidden imports. Each script has one job:

• prepare_sprite_run.py — prepare a run from request truth: write sprite-request.json, per-state layout guides, prompts, and empty raw/ and frames/ folders.
• extract_sprite_row_frames.py — read generated raw/.png strips, remove chroma background, extract connected sprite components, and write transparent frame PNGs plus frames/frames-manifest.json.
• compose_sprite_atlas.py — compose extracted frames into sprite-sheet-alpha.png and runtime manifest.json.frame_layout.
• preview_animation.py — build QA previews from extracted frames: contact sheets and state GIFs under qa/.
• compose_selected_cycle.py — record a human-selected frame subset as an explicit selected-cycle manifest plus QA GIF/contact sheet. Reads curation.json selection/transform by default; explicit --frames overrides it.
• compose_sprite_gif.py — export a clean transparent GIF from selected frame PNGs and optional frame order.
• gif_utils.py — shared transparent-GIF writer used by the GIF/QA scripts.
• curation.py — shared curation sidecar logic (schema + transform application) used by the compose scripts and the curation webview server. Single source of truth so they never drift.
• runio.py — shared safe run-dir IO: the single-writer run-dir lock (.sprite-gen.lock) and atomic temp+replace writes used by the extract/compose/export/unpack writers, so two agents (for example Claude Code and Codex in parallel) cannot silently interleave writes into one character folder.
• serve_curation.py — launch the standalone curation webview for one run dir (frame compare, select/reject, drag-to-reorder play sequence, non-destructive rotate/scale/move). Standalone so it works from Claude Code Desktop, the Codex app, or any environment where the skill is installed.
• unpack_atlas_run.py — inverse of compose: rebuild a curator-ready run dir (per-frame PNGs + synthesized sprite-request.json) from a finished sprite sheet, or import a folder of separate PNGs (--pngs-dir, e.g. a furniture pack). Layout source priority: explicit --grid COLSxROWS > --manifest rectangles > auto-detect (default). Auto-detect reads the atlas alpha and clusters content blobs into a grid, so it survives a character's internal transparency on packed sheets. With --pngs-dir, a sibling meta.json (item names + iso tile/anchor) is carried into the run so the curator can label items and draw the iso ground grid.
• export_curated_pngs.py — export curated frames back to named PNGs (the curation transform baked in), keeping each item's original filename. Output goes inside the run dir (/curated/, provably writable, cross-platform); the skill never writes elsewhere in your tree. The right deliverable for an imported still set (furniture); the single-atlas compose_sprite_atlas.py is the deliverable for animation frames / runtime perf.
• check_visible_magenta.py — optional screenshot QA guard for visible chroma-key leakage.

Standalone Curation View (이미지 후보 큐레이션 — 스프라이트 아님)

"큐레이션(뷰) 해줘 / 이미지 후보 보여줘 / 나란히 비교 / 골라볼게" 로 진입했고 대상이 애니메이션 프레임이 아니라 임의 이미지 후보군(아이콘 시안, 로고, 생성 초안)이면, 파이프라인 없이 이 단독 경로만 쓴다. 에이전트 채팅 surface 는 이미지를 못 보여주는 경우가 많다 — 이 웹뷰가 그 표시 수단이다.

SG=${ALEX_EXTENSIONS_DIR:-$HOME/Documents/workspace/personal/alex-extensions}/sprite-gen
STAGE=$(mktemp -d); mkdir -p "$STAGE/pngs"
cp  "$STAGE/pngs/"   # 의미 있는 이름으로: 1-hub-cube.png, 2-hook-plug.png ... (timestamp/uuid 파일명 금지)
python3 "$SG/scripts/unpack_atlas_run.py" --pngs-dir "$STAGE/pngs" --out-dir "$STAGE/run" --force
nohup python3 "$SG/scripts/serve_curation.py" --run-dir "$STAGE/run" --lang ko > "$STAGE/server.log" 2>&1 &
sleep 2
PORT=$(lsof -nP -a -p $! -iTCP -sTCP:LISTEN | awk 'END{sub(".*:","",$9); print $9}')   # stdout 버퍼링 때문에 log 대신 lsof 로 포트 확보
curl -s -o /dev/null -w "%{http_code}" "http://127.0.0.1:$PORT/"   # 200 = positive proof, 그 후 URL 보고

• 사용자 로컬이면 브라우저 자동 오픈이 기본, headless/원격이면 --no-open + URL 전달.
• 선택 회수는 "$STAGE/run/curation.json" 의 selected 인덱스를 파일명으로 역매핑. 비어 있으면 다시 묻는다 — 추측 진행 금지.
• 결정 후 서버 kill + $STAGE 정리. 후보가 1장이면 큐레이션이 아니다 — 경로만 보고하고 끝.

Simple MVP Scope

The default user promise is deliberately simple:

> A Codex user installs this skill, provides a character/base image and one or more simple actions, then receives a sprite sheet, GIF preview, and QA notes.

Do not frame the default path as game-ready humanoid locomotion. The current Codex/image-gen path is good at short readable pose changes, identity-preserving rows, chroma cleanup, atlas composition, and QA. It is not yet reliable enough to promise precise cyclic locomotion for humanoids.

Default/simple states:

• idle — stable default. Use 4 frames, loop true.
• jump — stable default as a short non-loop action. Use 4 frames, loop false.
• attack — stable default as a short non-loop action. Use 4 frames, loop false.
• wave — simple gesture, but only stable as non-loop unless the row includes a return-to-idle frame. Use 4 frames, loop false by default; use 5 frames only when the final frame intentionally returns near frame 1.
• talk, blink, bounce, hurt, celebrate, magic_cast — allowed simple candidates, but still require motion QA before pass.

Experimental states:

• walk, run, frontwalk, 45_frontwalk, and other cyclic locomotion.
• Directional cycles that require exact foot-contact alternation or phase symmetry.
• Any state where the user needs game-ready locomotion rather than a readable preview animation.

For experimental states, report them as experimental in qa-notes.md unless motion QA passes. Never silently promote a weak walk/run row to the same status as simple MVP output.

Quick Path For Simple Animations

When the user asks for "simple sprite animation", prefer this request shape unless they specify otherwise:

{
  "states": {
    "idle": { "frames": 4, "fps": 4, "loop": true, "action": "subtle breathing and one blink" },
    "attack": { "frames": 4, "fps": 8, "loop": false, "action": "simple windup, strike, recovery attack pose sequence with no detached effects" },
    "jump": { "frames": 4, "fps": 8, "loop": false, "action": "simple jump arc: crouch, takeoff, airborne, landing" }
  }
}

Add wave only as a non-loop gesture by default:

"wave": { "frames": 4, "fps": 6, "loop": false, "action": "friendly hand wave gesture; arm changes clearly while feet stay planted" }

Simple MVP pass requires:

• automated extraction and atlas reports pass
• qa/.gif reads as the requested simple action
• loop seam passes for looped states
• non-loop states have clear start/middle/end pose progression
• qa-notes.md records pass, best-effort, or experimental per state

Frame Count Guidance

Keep default simple actions short. More frames do not automatically create smoother animation in the current component-row image generation path:

• 4 frames is the default stable range for simple actions.
• 5 frames is acceptable when a non-loop gesture needs a return-to-idle pose.
• 6 frames is the conservative upper edge for simple humanoid one-shot defaults.
• 8 frames is hatch-pet-style advanced territory, not forbidden. Use it for compact mascots, locomotion rows, or explicit experiments only when extraction/motion QA passes.
• 9 and 12 frames are not default simple settings. In validation runs, they increased duplicate bodies, empty/sparse frames, slot collapse, and extraction failure before adding useful in-betweens.

If a user asks for 9 or 12 frames, run it as an explicit experiment and report duplicate-heavy, blur/merge, or extract-fail honestly instead of treating it as a normal pass.

Idle Anchor Architecture (Stage 0, BLOCKING)

The row-generation pipeline has one hard ownership rule:

identity truth = accepted idle anchor
motion truth   = layout guide + paired/basis row when needed
base truth     = used only to create idle anchors, then removed from row inputs

Base character images, original character sheets, and broad style references are allowed only before idle anchors are accepted. Once an idle anchor exists for the requested direction, later state rows must not attach the base character image as insurance. Re-attaching base makes the row model solve identity again and weakens the purpose of the idle-anchor workflow.

Reference ownership flow:

[USER REFS / CHARACTER SHEET]
          |
          v
+-----------------------------+
| 0. BASE IDLE 생성            |
| - 원본/캐릭터시트는 여기서만 사용 |
| - 비율/스타일/색/소품 고정       |
+-----------------------------+
          |
          v
+-----------------------------+
| 1. 방향별 IDLE ANCHOR 생성    |
| - idle-front-right           |
| - idle-front-left            |
| - idle-back-right            |
| - idle-back-left             |
+-----------------------------+
          |
          v
        BASE CHARACTER 폐기
        original refs 폐기
        character sheet 폐기
        이후 row 입력 금지
          |
          v
+-----------------------------+
| 2. BASIS ROW 생성            |
| input:                       |
| - target-direction idle      |
| - target-state layout only   |
| output: basis row            |
+-----------------------------+
          |
          v
+-----------------------------+
| 3. PAIRED ROW 생성           |
| input:                       |
| - paired-direction idle      |
| - paired-state layout only   |
| - basis row                  |
| output: paired row           |
+-----------------------------+
          |
          v
+-----------------------------+
| 4. GIF / SHEET 조립          |
| - row crop                   |
| - gif preview                |
| - frame-index QA             |
+-----------------------------+

A weak idle anchor poisons every state — proportions, style, and identity drift compound across all rows. So before any row generation you must pass an explicit gate.

Gate question, answered y/n:

> Is there an image good enough to lock as the canonical base idle?

The base idle locks only when all of these hold:

• Full body, nothing cropped (head to feet inside frame).
• The final proportions and style the user asked for are already correct in this image (for example SD / chibi head-to-body ratio, pixel look, outline weight). The base defines the target — do not plan to "fix it later" in the rows.
• Identity matches the character sheet / reference (face, hair, markings, palette, props).
• One clear single idle pose, facing the intended camera, readable silhouette at small size.
• Background is a flat clean chroma-ready fill (or trivially keyable).

If the answer is n: generate/iterate base candidates, review each against the criteria above, and re-gate. Do not run prepare_sprite_run.py until a base is locked. "Good enough for now" is not a pass — drift only grows once the rows start.

When the answer is y, that exact file becomes the accepted idle anchor for its direction. Keep the original generation around so the lock decision is auditable, but do not attach it again after the idle anchors have replaced it as row identity truth.

License And Attribution

sprite-gen is released under Apache-2.0. The component-row workflow is inspired by the Apache-2.0 licensed hatch-pet skill, but this project does not include Codex pet assets, pet packages, or hatch-pet visual assets.

SSoT

Every run starts with sprite-request.json. It owns the numeric recipe used by prompts and scripts:

{
  "version": 1,
  "kind": "sprite-gen-request",
  "engine": "component-row",
  "character": { "id": "howl", "description": "same character as the base image" },
  "cell": { "shape": "square", "size": 256, "safe_margin": 24 },
  "chroma_key": { "name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255] },
  "states": {
    "idle": { "frames": 4, "fps": 4, "loop": true, "action": "subtle breathing and blinking" },
    "attack": { "frames": 4, "fps": 8, "loop": false, "action": "simple windup, strike, recovery attack pose sequence with no detached effects" },
    "jump": { "frames": 4, "fps": 8, "loop": false, "action": "jump arc through body position only" },
    "wave": { "frames": 4, "fps": 6, "loop": false, "action": "friendly hand wave gesture; arm changes clearly while feet stay planted" }
  }
}

256 is a default variable, not a hidden constant. Change it through the request, then regenerate guides, prompts, extraction, and atlas from the same request.

Rectangular generation cells are allowed when the target motion benefits from hatch-pet-style row proportions:

"cell": { "shape": "rect", "width": 192, "height": 208, "safe_margin_x": 18, "safe_margin_y": 16 }

The generated row uses the request cell shape. The final atlas is still consumed through manifest.json.frame_layout; runtime code must not assume square cells.

Workflow

1. Pass the Base Lock Gate above. Do not start step 1 until a base idle is locked (y).

1. Prepare the run:

python3 $ALEX_EXTENSIONS_DIR/sprite-gen/scripts/prepare_sprite_run.py \
  --out-dir /assets/generated/sprites/ \
  --character-id  \
  --base-image /absolute/path/to/base.png \
  --description "" \
  --force

For hatch-pet-style locomotion, add the cell gate explicitly:

  --cell-width 192 \
  --cell-height 208

This writes:

sprite-request.json
base-source.
references/layout-guides/.png
prompts/.txt
raw/
frames/

1. Generate one image per state with kuma:image-gen.

For simple/default states before direction-anchor mode exists, attach exactly two references:

• base-source. — canonical character identity
• references/layout-guides/.png — layout-only guide

For direction-anchor mode, do not attach base-source. to action rows. Attach the accepted target-direction idle anchor plus the state layout guide. For a paired row, also attach the already generated basis row as timing/scale/motion reference only.

For hatch-pet-style locomotion, attach additional references only when they are part of the row plan and record them in qa-notes.md. Useful advanced references are:

• original character reference / sheet — identity support only
• canonical base image — identity support only
• previous generated gait row, such as raw/running-right.png for running-left — motion rhythm only
• accepted previous motion QA artifact, such as qa/-contact.png or an approved selected-cycle contact sheet — gait readability support only

Use prompts/.txt as the prompt. Save the selected generated image as raw/.png.

1. Extract frames:

python3 $ALEX_EXTENSIONS_DIR/sprite-gen/scripts/extract_sprite_row_frames.py \
  --run-dir /assets/generated/sprites/

This removes the request chroma key, finds connected sprite components, fits each pose into a fresh transparent request-sized cell, and writes frames//frame-N.png plus frames/frames-manifest.json.

3.5. (Optional) Curate frames in the webview:

python3 $ALEX_EXTENSIONS_DIR/sprite-gen/scripts/serve_curation.py \
  --run-dir /assets/generated/sprites/

This launches a standalone local webview (no Studio dependency — usable from Claude Code Desktop, the Codex app, or any host with the skill installed). It shows every state's frames side by side so you can compare them in parallel, toggle which frames are selected, drag the ⠿ grip on a card to reorder the play sequence or move it between the two rows — a sequence row (the selected play order, saved

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aldegad
• Source: aldegad/sprite-gen
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.