Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
gen-set: default concurrency 6, the lead-verified batch width
Soohong Kim8241da7c97f4
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1f0fed1..339217a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -29,7 +29,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the### Added- `sprite_gen/video/` domain and the verbs `video-canvas`, `video-frames`, `video-loop`, `video-set` (contract: `docs/video-pipeline.md`). `video-loop --cycle auto|periodic|one-shot`: action states (`jump`, `attack`, unknown) whose clip performs the action once get a recorded one-shot cut (rest → excursion → rest) instead of a hard failure; the report keeps the rejected periodic attempt and `table.md` gains a `kind` column. `walk`, `run`, `idle` still fail loud without a period.-- `sprite-gen gen-set` (`sprite_gen/gen/gen_set.py`, `scripts/gen_set.py`): anchors before rows on direction runs, reuse unless `--force`, `reports/gen-set/table.md` + `set.report.json`, `--provider` honoured verbatim with `gen`'s own default resolution and its recorded codex → grok availability failover per row.+- `sprite-gen gen-set` (`sprite_gen/gen/gen_set.py`, `scripts/gen_set.py`): 6 rows at a time by default (the lead-verified batch width), anchors before rows on direction runs, reuse unless `--force`, `reports/gen-set/table.md` + `set.report.json`, `--provider` honoured verbatim with `gen`'s own default resolution and its recorded codex → grok availability failover per row.- `sprite_gen._modules.DOMAINS` / `domain_of()`: display order and one-line meaning per domain; `cli.command_domains()` derives the help groups. A verb whose module is not in the table fails loudly.- `docs/README.md` (documentation index) with a test that pins it to the file set and resolves every relative markdown link; tables of contents in `run-contract.md`, `layer-tracks.md`, `curation.md`, `directional-anchor-workflow.md`, `architecture.md`; `scripts/dev/README.md`.diff --git a/SKILL.md b/SKILL.mdindex bb00f08..322c9cf 100644--- a/SKILL.md+++ b/SKILL.md@@ -143,7 +143,7 @@ $SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/prepare_sprite_run.pyHatch-pet-style locomotion adds the cell gate (`--cell-width 192 --cell-height 208`). Directional characters declare the direction contract (`--directions down,side,up --mirror left=side`); files then follow the taxonomy `raw/<dir>/<pose>.png`, `frames/<dir>/<pose>/` (path resolver SSoT `sprite_gen/layout.py`, frame paths SSoT = frames-manifest `row.files`) and `prepare` records the generation chain in `references/generation-plan.json` — [`docs/directional-anchor-workflow.md`](docs/directional-anchor-workflow.md). Writes `sprite-request.json`, `base-source.<ext>`, `references/layout-guides/<state>.png`, `prompts/<state>.txt`, `raw/`, `frames/`.-2. Generate the rows (the one AI step; the `image-gen` skill is a thin shuttle over this). The batch form is the default — `$SPRITE_GEN_ROOT/.venv/bin/sprite-gen gen-set --run-dir <run>` generates every non-mirrored state 4 at a time with the run's own identity ref and writes `reports/gen-set/table.md`; one row by hand:+2. Generate the rows (the one AI step; the `image-gen` skill is a thin shuttle over this). The batch form is the default — `$SPRITE_GEN_ROOT/.venv/bin/sprite-gen gen-set --run-dir <run>` generates every non-mirrored state 6 at a time with the run's own identity ref and writes `reports/gen-set/table.md`; one row by hand:```bash$SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image.py \@@ -153,7 +153,7 @@ $SPRITE_GEN_ROOT/.venv/bin/python $SPRITE_GEN_ROOT/scripts/generate_sprite_image- `--provider` is optional: default codex (`SPRITE_GEN_DEFAULT_PROVIDER` overrides; observable grok fallback only if codex is unavailable). Rows keep the request chroma key and are generated **without** `--transparent`; standalone stills use `--transparent` (codex native alpha first, grok chroma) — [`docs/gen.md`](docs/gen.md).- References: default states attach exactly two — `base-source.<ext>` + the state layout guide. Direction-anchor mode attaches the accepted anchor instead of the base: **never pick the anchor crop by hand**, ask `$SPRITE_GEN_ROOT/.venv/bin/python -m sprite_gen.cli anchor --run-dir <run> --for-state <state>` right before each generation (derived cache, re-run every time; the human pins which frame). Extra motion references only when recorded in `qa-notes.md`.-- **Concurrency (maintainer 2026-07-19)**: multi-row batches run **4 at a time** — that is `gen-set`'s default `--concurrency`; serial one-by-one is an anti-pattern. `runio.py` locks make parallel `raw/<state>.png` writes safe. Providers are engine backends, not agents — no worker surface is spawned ([`docs/gen.md`](docs/gen.md#provider-topology)).+- **Concurrency (lead-verified 2026-08, no throttling at 6)**: multi-row batches run **6 at a time** — that is `gen-set`'s default `--concurrency`; serial one-by-one is an anti-pattern. `runio.py` locks make parallel `raw/<state>.png` writes safe. Providers are engine backends, not agents — no worker surface is spawned ([`docs/gen.md`](docs/gen.md#provider-topology)).3. Extract frames — chroma removal, connected components, one transparent request-sized cell per pose, `frames/<state>/frame-N.png` + `frames/frames-manifest.json`:diff --git a/docs/gen.md b/docs/gen.mdindex 31f6fd3..b50e2df 100644--- a/docs/gen.md+++ b/docs/gen.md@@ -165,8 +165,8 @@ exactly that, rather than falling back on its own.## Sprite-row usageIn the atlas pipeline (SKILL.md §2) the rows of a prepared run are generated by-`sprite-gen gen-set --run-dir <run>`: every non-mirrored state, `--concurrency` 4 at a-time, each row with the identity ref the run declares (`base-source.*`, or the accepted+`sprite-gen gen-set --run-dir <run>`: every non-mirrored state, `--concurrency` 6 at a+time (lead-verified: no provider throttling at 6), each row with the identity ref the run declares (`base-source.*`, or the accepteddirection anchor for a direction-contract action row — `sprite_gen.curate.anchor` ownsthat choice) plus its layout guide, into `raw/<state>.png`. Each row gets`reports/gen-set/<state>.json`, the batch writes `reports/gen-set/table.md` anddiff --git a/sprite_gen/gen/gen_set.py b/sprite_gen/gen/gen_set.pyindex 9f4b5f8..78e5f67 100644--- a/sprite_gen/gen/gen_set.py+++ b/sprite_gen/gen/gen_set.py@@ -35,7 +35,7 @@ from sprite_gen.curate import anchor as anchor_modfrom sprite_gen.spec import layoutfrom sprite_gen.spec.runio import atomic_write_text-DEFAULT_CONCURRENCY = 4 # maintainer 2026-07-19: multi-row batches run 4 at a time; serial is the anti-pattern+DEFAULT_CONCURRENCY = 6 # lead-verified 2026-08 (no provider throttling at 6-wide); serial one-by-one is the anti-patternREPORT_DIR = "reports" # <run>/reports/gen-set/<state>.json — outside raw/ and frames/, the run contract's derived areas