/game-sprite-pipeline

name: game-sprite-pipeline
version: 2.0.0
description: "AI sprite generation: portraits, idle loops, animated sheets via Codex/Nano Banana. Per-row generation, animation presets, video-to-sprite, identity lock. Use for generated character art."
agent: python-general-engineer
user-invocable: false
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Edit
routing:
  triggers:
    - AI sprite
    - AI character art
    - generate character
    - generate sprite
    - generate wrestler
    - generate character portrait
    - spritesheet pipeline
    - animated spritesheet
    - animated sprite
    - portrait loop
    - idle loop
    - road-to-aew sprite
    - sprite for road-to-aew
    - wrestler portrait
    - character sheet
    - fighter spritesheet
    - RPG character spritesheet
    - platformer spritesheet
    - per-row sprite generation
    - video to sprite
    - animation preset
    - deterministic idle
    - breathing loop
    - sprite QA
    - contact sheet
  complexity: Complex
  category: game
  pairs_with:
    - phaser-gamedev
    - threejs-builder
    - python-general-engineer
    - game-pipeline

Game Sprite Pipeline

Local-first AI sprite generation. One skill, four modes behind `--mode`:

• `portrait` — single full-body character PNG (road-to-aew wrestlers, card-game characters).
• `portrait-loop` — 2×2 = 4-frame subtle idle (breathing + blink) at 200ms/frame in ONE Codex call. Animated portraits without re-prompting new poses.
• `spritesheet` — animated multi-frame grid with connected-components detection, ground-line anchor alignment, and Phaser atlas output.
• `spritesheet --per-row` — row-strip generation: each animation state generated as a separate strip with layout guide grounding and identity lock, then composited into a final sheet. Eliminates cross-row contamination and reduces retry scope from whole-sheet to single-row.

Backend chain (per ADR-198): Codex CLI imagegen is the default when installed and authed. When Codex is unavailable AND `GEMINI_API_KEY` (or `GOOGLE_API_KEY`) is set, the skill falls back to Nano Banana via `nano-banana-builder`'s scripts. When neither is available, the skill fails loud with `BackendUnavailableError` listing both fix paths. Both paths use keys the user already holds — there is no third-party billing the toolkit hides. Reference implementation of the "Local-First, Deterministic Systems Over External APIs" principle in `docs/PHILOSOPHY.md` (user-owned-key clause).

When to use

| User says | Mode | Entry script | |-----------|------|--------------| | "generate a wrestler portrait" | `portrait` | `portrait_pipeline.py` | | "add a new enemy to road-to-aew" | `portrait` | `portrait_pipeline.py --target road-to-aew` | | "animated idle portrait" / "subtle breathing loop" | `portrait-loop` | `portrait_pipeline.py --mode portrait-loop` | | "make a walk cycle spritesheet" | `spritesheet` | `sprite_pipeline.py` | | "4-direction character sheet" | `spritesheet` | `sprite_pipeline.py --grid 4x4` | | "Phaser-ready texture atlas" | `spritesheet` | `sprite_pipeline.py` (emits atlas JSON) | | "generate a fighter spritesheet" | per-row + preset | `sprite_pipeline.py --preset fighter --per-row` | | "RPG character walk cycle" | per-row + preset | `sprite_pipeline.py --preset rpg-character --per-row` | | "sprite from video clip" | video | `video_extract_frames.py` + `video_select_frames.py` + `video_process_frames.py` |

Portrait is the road-to-aew immediate need; spritesheet is the forward-looking capability. Both share one backbone (prompt scaffolding, backend dispatch, bg removal, validation).

Reference Loading Table

| Signal | Load | Why | |--------|------|-----| | picking a style preset | `references/style-presets.md` | 9 era/hardware presets + custom slot | | `--target road-to-aew` or `--archetype` | `references/wrestler-archetypes.md` | 9 color archetypes + 10 gimmick types + tier | | sizing `--grid CxR` / `--cell-size` | `references/grid-shapes.md` | allowed dims, direction conventions | | building a prompt | `references/prompt-rules.md` | ART_STYLE, CHAR_STYLE, GRID_RULES slot contents | | picking or troubleshooting a backend | `references/backend-chain.md` | Codex CLI invocation pattern + failure modes | | spritesheet Phase D | `references/frame-detection.md` | connected-components algorithm | | spritesheet Phase F | `references/anchor-alignment.md` | shared-scale + bottom-anchor math | | any bg removal phase | `references/bg-removal-local.md` | magenta chroma + rembg | | Phase H assembly / output shape | `references/output-formats.md` | PNG / GIF / WebP / atlas JSON | | any phase errors | `references/error-catalog.md` | failure mode → fix mapping | | user reports clipping / blank cells / cut effects | `references/error-catalog.md` (top section) | "Codex Regeneration as a Post-Processing Fix" failure mode; debug slicer, never raw | | asset has effects (fire, projectile trails, auras, extended limbs) | `references/error-catalog.md` + use `slice_with_content_awareness` | content extending past cell boundaries needs centroid-ownership extraction. ADR-207 RC-1: on dense grids (`cols * rows >= 16` AND both dims >= 4) `--content-aware-extraction` is silently downgraded to strict-pitch with a warning unless `--effects-asset` is also passed (orchestrator-side) or `effects_asset: True` is set (spec-side). Use `--effects-asset` only for genuine sparse-but-cross-boundary content (fire breath, plasma trails, projectile auras). | | `--target road-to-aew` deploy | `references/road-to-aew-integration.md` | snake_case, paths, manifest regen | | `--per-row` subagent orchestration | `references/subagent-delegation.md` | subagent boundary rules: who generates, who composes, who finalizes | | VFX issues in per-row prompts | `references/vfx-containment.md` | full containment ruleset: allowed/forbidden effects, per-state rules |

Read the references whose signals match the task — references load on demand, so the cost is paid once p