From 26b287438cd1138f3003ea4f358d6b4b9ae244b5 Mon Sep 17 00:00:00 2001 From: Claude Code Date: Thu, 26 Mar 2026 11:38:32 -0700 Subject: [PATCH] =?UTF-8?q?docs(sprite-generation):=20=F0=9F=93=9D=20Updat?= =?UTF-8?q?e=20sprite=20generation=20tool=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Lilith Autocommit --- tools/sprite-generation/docs/PIPELINE.md | 157 +++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 tools/sprite-generation/docs/PIPELINE.md diff --git a/tools/sprite-generation/docs/PIPELINE.md b/tools/sprite-generation/docs/PIPELINE.md new file mode 100644 index 00000000..0595a53d --- /dev/null +++ b/tools/sprite-generation/docs/PIPELINE.md @@ -0,0 +1,157 @@ +# Sprite Generation Pipeline + +## Overview + +A single long-running process (`cli.py run`) continuously moves sprites from `needed` → `installed` with minimal human intervention. The human's only job is picking winners in the Review GUI. + +``` + ┌─────────────────────────────────────────┐ + │ ORCHESTRATOR │ + │ (cli.py run — daemon) │ + │ │ + ┌────────┐ auto │ ┌──────────┐ auto ┌──────────┐ │ + │ SCAN │─────────────▶│ │ GENERATE │──────▶│ RANK │ │ + │ │ │ │ model- │ │ (Sonnet) │ │ + │ JSON │ │ │ boss GPU │ │ vision │ │ + │ → DB │ │ │ 4 var/ea │ │ auto │ │ + └────────┘ │ └────┬─────┘ └────┬─────┘ │ + │ │ │ │ + │ │ ┌──────────────┘ │ + │ │ │ score < threshold? │ + │ │ │ yes → back to GENERATE │ + │ │ │ no → move to REVIEW │ + │ ▼ ▼ │ + │ ┌──────────────┐ │ + │ │ REVIEW QUEUE │◀── Sonnet-ranked │ + │ │ (ready for │ sprites waiting │ + │ │ human pick) │ for approval │ + │ └──────┬───────┘ │ + └─────────┼──────────────────────────────┘ + │ + ┌────────▼────────┐ + │ REVIEW GUI │ ◀── human picks + │ (theater) │ best variant + │ click approve │ + └────────┬────────┘ + │ + ┌────────▼────────┐ + │ INSTALL │ auto on approve + │ chroma key rm │ + │ resize │ + │ → game assets │ + │ → manifest DB │ + └─────────────────┘ +``` + +## Orchestrator Loop (`cli.py run`) + +```python +while True: + # 1. Pick sprites that need work + needed = get_sprites(status="needed", limit=BATCH_SIZE) + + # 2. Generate variants (4 per sprite, with pose reference) + for sprite in needed: + generate_batch([sprite.id], variants_per=4, pose_ref=POSE_REF) + # sprite auto-transitions: needed → review + + # 3. Rank newly completed sprites + in_review = get_sprites(status="review", unranked=True) + for sprite in in_review: + result = rank_and_filter(sprite.id) + if result.needs_regen: + # Not enough good variants → back to needed + reset_sprite(sprite.id) # will be re-generated next loop + + # 4. Sleep between batches (let GPU breathe) + sleep(30) +``` + +## State Machine + +``` +needed ──generate──▶ review ──rank──▶ review (ranked) + ▲ │ + │ │ + └── needs_regen ◀── score < threshold ──┘ + │ + score ≥ threshold + │ + ▼ + review (ready) + │ + human approve + │ + ▼ + approved + │ + auto process + + install + │ + ▼ + installed +``` + +## Key Behaviors + +### Auto-regeneration +When Sonnet ranks a sprite and fewer than 3 variants pass the confidence threshold, the sprite resets to `needed` and gets 4 more variants on the next loop. Old variants are kept (accumulative). Eventually enough good variants accumulate. + +### Pose Reference +All unit generation uses an approved southwest-facing sprite as img2img reference (strength 0.6). This ensures consistent facing direction across the roster. The reference sprite is configured once and used for all unit generation. + +### Rate Limiting +- Generator submits requests with retry + exponential backoff (10s, 20s, 40s...) +- model-boss queues internally (1 concurrent diffusion request) +- Orchestrator batches work in small groups (4-8 sprites) with sleep between batches + +### Review GUI +- Sprite Theater shows all generated sprites sorted by recency +- Each card shows #ID, entity name, category, Sonnet scores +- Click to open detail → approve winner +- Approve triggers: chroma key removal → resize → install to game assets → manifest DB update + +## CLI Commands + +```bash +# Full pipeline daemon (scan + generate + rank loop) +./run tools spritegen run + +# Individual steps (for debugging) +./run tools spritegen scan --demo +./run tools spritegen generate --category units --variants 4 --pose-ref raw/reference.png +./run tools spritegen rank +./run tools spritegen approve +./run tools spritegen status + +# Review GUI +./run tools spritegen start # http://localhost:5850 +``` + +## File Flow + +``` +game JSON data + │ + ▼ +sprites.db (pipeline state) + │ + ├──generate──▶ raw/{sprite_id}_{variant_id}.png (1024×1024, green bg) + │ │ + │ rank (Sonnet) + │ │ + │ ▼ + │ sprites.db (variant.rating, variant.notes) + │ │ + │ human approve + │ │ + │ ▼ + ├──process──▶ variants/{sprite_id}_{variant_id}.png (256×256, transparent) + │ │ + │ install + │ │ + │ ▼ + ├──install──▶ games/age-of-four/assets/sprites/units/{id}_{race}_{g}.png + │ + └──manifest─▶ games/age-of-four/data/sprites.db (game runtime manifest) +```