docs(sprite-generation): 📝 Update sprite generation tool documentation
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
Claude Code
parent
cfa7142e26
commit
26b287438c
1 changed files with 157 additions and 0 deletions
157
tools/sprite-generation/docs/PIPELINE.md
Normal file
157
tools/sprite-generation/docs/PIPELINE.md
Normal file
|
|
@ -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 <variant_id>
|
||||
./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)
|
||||
```
|
||||
Loading…
Add table
Reference in a new issue