Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

scripts: one wrapper per verb; experiments under scripts/dev; compat aliases removed

Soohong Kim496f1ef3201e
diff --git a/SKILL.md b/SKILL.md
index 2bd6f5a..144e41d 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -31,9 +31,7 @@ depends_on:
- scripts/inspect_sprite_run.py
- scripts/score_sprite_run.py
- scripts/run_correction_loop.py
- - scripts/gif_utils.py
- scripts/curation.py
- - scripts/runio.py
- scripts/serve_curation.py
- scripts/slice_sheet_cells.py
- scripts/unpack_atlas_run.py
@@ -126,7 +124,7 @@ One job each, all under `scripts/` (wrappers) ↔ `sprite_gen/<domain>/` (impl).
| `recolor.py` (`recolor` / `recolor-palette`) | deterministic palette-swap bake → `variants/` + report (exact match; opt-in tolerance) | [`docs/recolor.md`](docs/recolor.md) |
| `compose_layers.py` (`sprite-gen compose-layers`) | rig runs only: curated rows stacked by integer pivots + masks → `layers/` (all-or-nothing) | [`docs/layer-tracks.md`](docs/layer-tracks.md) |
| `unpack_atlas_run.py` (`unpack-atlas`) · `export_curated_pngs.py` (`export-pngs`) | finished sheet / PNG folder → curator-ready run · curated frames → named PNGs (`curated/`) | [`docs/curation.md`](docs/curation.md) |
-| `cutout` · `slice_sheet_cells.py` (`slice-sheet`) · `check_visible_magenta.py` | imported-image background removal (white matte / chroma engine) · multi-figure sheet → per-cell cuts · screenshot chroma-leak guard | [`docs/sheet-slicing.md`](docs/sheet-slicing.md) |
+| `cutout` · `slice_sheet_cells.py` (`slice-sheet`) · `dev/check_visible_magenta.py` | imported-image background removal (white matte / chroma engine) · multi-figure sheet → per-cell cuts · screenshot chroma-leak guard | [`docs/sheet-slicing.md`](docs/sheet-slicing.md) |
Breathing (idle) and static-pose rows are a **post-process layer** declared in `curation.json` (`states.<state>.breathe`) and baked by compose — never a script step; the contract (anatomy detection, editor, rigid boundary, `migrate-breathe`) is [`docs/breathing.md`](docs/breathing.md) and [`docs/static-pose-recipe.md`](docs/static-pose-recipe.md).
diff --git a/docs/run-contract.md b/docs/run-contract.md
index 2d59698..f5093cc 100644
--- a/docs/run-contract.md
+++ b/docs/run-contract.md
@@ -40,7 +40,7 @@ canonical files, not hidden imports.
| Selected cycle | `compose_selected_cycle.py` | `curation.json` / `--frames` | selected-cycle manifest + QA |
| Inverse / import | `unpack_atlas_run.py` | finished atlas **or** `--pngs-dir` | curator-ready run dir (§4) |
| Export stills | `export_curated_pngs.py` | curated `frames/` | named PNGs under `curated/` |
-| Chroma guard | `check_visible_magenta.py` | screenshot | leakage warning |
+| Chroma guard | `scripts/dev/check_visible_magenta.py` | screenshot | leakage warning |
The happy path is `prepare → gen → extract → (curate) → compose`, with a curation
webview opened as the closing step. Stage internals (chroma removal, connected
diff --git a/scripts/dev/README.md b/scripts/dev/README.md
new file mode 100644
index 0000000..9fb96ba
--- /dev/null
+++ b/scripts/dev/README.md
@@ -0,0 +1,13 @@
+# scripts/dev — maintainer experiments, not pipeline stages
+
+These are not `sprite-gen` verbs and the skill never requires them. Each one is a
+measurement or a proof that fed a rule now living in the package or its docs:
+
+| Script | What it measures |
+|---|---|
+| `breathe_mutation_battery.py` | plants each breathe-contract mutation in the source and checks the tests bite (exit 0 = every net bites) |
+| `measure_align_sigma.py` | per-frame horizontal jitter σ of `fit.align_x` variants on a source run's raw strips |
+| `validate_pr6_subject_profile.py` | same-raw A/B proof for the subject-specific sparse floor (PR #6) |
+| `check_visible_magenta.py` | chroma-leak guard for screenshots (`sprite_gen.frames.check_visible_magenta`) |
+
+Run them with the project interpreter (`.venv/bin/python scripts/dev/<name>.py`).
diff --git a/scripts/breathe_mutation_battery.py b/scripts/dev/breathe_mutation_battery.py
similarity index 99%
rename from scripts/breathe_mutation_battery.py
rename to scripts/dev/breathe_mutation_battery.py
index c8883fb..7edcdb4 100644
--- a/scripts/breathe_mutation_battery.py
+++ b/scripts/dev/breathe_mutation_battery.py
@@ -1,6 +1,6 @@
"""호흡 계약 변이 배터리 — 그물을 손대면 **전부** 다시 돌린다.
- python scripts/breathe_mutation_battery.py
+ python scripts/dev/breathe_mutation_battery.py
각 항목은 "이 계약이 깨지면 어떤 코드가 되는가" 를 소스에 잠깐 심고, 그물이 실제로
무는지(테스트가 FAIL 하는지) 확인한 뒤 되돌린다. 전부 물어야 exit 0 이다.
diff --git a/scripts/check_visible_magenta.py b/scripts/dev/check_visible_magenta.py
similarity index 87%
rename from scripts/check_visible_magenta.py
rename to scripts/dev/check_visible_magenta.py
index bf06abc..6f1e643 100644
--- a/scripts/check_visible_magenta.py
+++ b/scripts/dev/check_visible_magenta.py
@@ -5,7 +5,7 @@
import sys
from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
import sprite_gen.frames.check_visible_magenta as _impl
diff --git a/scripts/measure_align_sigma.py b/scripts/dev/measure_align_sigma.py
similarity index 97%
rename from scripts/measure_align_sigma.py
rename to scripts/dev/measure_align_sigma.py
index e37e9bd..11e6c5f 100644
--- a/scripts/measure_align_sigma.py
+++ b/scripts/dev/measure_align_sigma.py
@@ -10,7 +10,7 @@ bottom-20% foot band) inside the final cells. σ is the jitter a player sees as
the body axis wobbling during playback.
Usage:
- python3 scripts/measure_align_sigma.py \
+ python3 scripts/dev/measure_align_sigma.py \
--run-dir <run with sprite-request.json + raw/> \
--states down_walk,down_run \
--variants foot-centroid,alpha-centroid
@@ -24,7 +24,7 @@ import sys
import tempfile
from pathlib import Path
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
from PIL import Image
diff --git a/scripts/validate_pr6_subject_profile.py b/scripts/dev/validate_pr6_subject_profile.py
similarity index 99%
rename from scripts/validate_pr6_subject_profile.py
rename to scripts/dev/validate_pr6_subject_profile.py
index 950b019..1009182 100644
--- a/scripts/validate_pr6_subject_profile.py
+++ b/scripts/dev/validate_pr6_subject_profile.py
@@ -14,7 +14,7 @@ from pathlib import Path
from PIL import Image, ImageDraw, ImageFont
-ROOT = Path(__file__).resolve().parents[1]
+ROOT = Path(__file__).resolve().parents[2]
PYTHON = Path(sys.executable)
EXTRACT = ROOT / "scripts" / "extract_sprite_row_frames.py"
COMPOSE = ROOT / "scripts" / "compose_sprite_atlas.py"
diff --git a/scripts/extract.py b/scripts/extract.py
deleted file mode 100644
index 58c7642..0000000
--- a/scripts/extract.py
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Apache-2.0
-"""Backward-compatible wrapper for sprite_gen.frames.extract."""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-import sprite_gen.frames.extract as _impl
-
-globals().update({name: value for name, value in vars(_impl).items() if name not in {"__name__", "__package__", "__loader__", "__spec__"}})
diff --git a/scripts/gif_utils.py b/scripts/gif_utils.py
deleted file mode 100755
index bf76bfa..0000000
--- a/scripts/gif_utils.py
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Apache-2.0
-"""Backward-compatible wrapper for sprite_gen.util.gif_utils."""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-import sprite_gen.util.gif_utils as _impl
-
-globals().update({name: value for name, value in vars(_impl).items() if name not in {"__name__", "__package__", "__loader__", "__spec__"}})
diff --git a/scripts/reroll_state_row.py b/scripts/reroll_state_row.py
deleted file mode 100644
index a3ffba0..0000000
--- a/scripts/reroll_state_row.py
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Apache-2.0
-"""Backward-compatible wrapper for sprite_gen.effects.reroll."""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-import sprite_gen.effects.reroll as _impl
-
-globals().update({name: value for name, value in vars(_impl).items() if name not in {"__name__", "__package__", "__loader__", "__spec__"}})
-
-
-if __name__ == "__main__":
- raise SystemExit(_impl.main())
diff --git a/scripts/runio.py b/scripts/runio.py
deleted file mode 100644
index 3aa26d3..0000000
--- a/scripts/runio.py
+++ /dev/null
@@ -1,12 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: Apache-2.0
-"""Backward-compatible wrapper for sprite_gen.spec.runio."""
-
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
-
-import sprite_gen.spec.runio as _impl
-
-globals().update({name: value for name, value in vars(_impl).items() if name not in {"__name__", "__package__", "__loader__", "__spec__"}})
diff --git a/tests/effects/test_breathe_off_state.py b/tests/effects/test_breathe_off_state.py
index 3c590b0..a680591 100644
--- a/tests/effects/test_breathe_off_state.py
+++ b/tests/effects/test_breathe_off_state.py
@@ -25,7 +25,7 @@ validator 검증 2026-07-25).
- 계약을 **진짜로** 지키는 것은 동작 테스트다: `tests/test_breathe_reference_key.py` 가
실제 `store.js`/`breathe.js` 를 node 로 돌려 서버 페이로드와 왕복 대조한다. 계약을
강화할 여지가 있으면 **거기에** 추가하는 것이 옳고, 여기 정규식을 조이는 것이 아니다.
-- 이 스캐너들이 실제로 잡은 회귀는 `scripts/breathe_mutation_battery.py` 에 변이로 남아
+- 이 스캐너들이 실제로 잡은 회귀는 `scripts/dev/breathe_mutation_battery.py` 에 변이로 남아
있다. 그물을 손대면 배터리 전건을 재실행한다 (새 변이만 확인하는 것으로는 부족하다 —
그물 자신의 개선이 다른 축을 여는 일이 반복됐다).