Skip to content

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

refactor(run-files): sprite-request.json, curation.json and the PNG signature read REQUEST_FILENAME, CURATION_FILENAME and base.PNG_MAGIC where they were spelt again

Soohong Kimffbd5a413649
diff --git a/scripts/dev/measure_align_sigma.py b/scripts/dev/measure_align_sigma.py
index 11e6c5f..c33a1f4 100644
--- a/scripts/dev/measure_align_sigma.py
+++ b/scripts/dev/measure_align_sigma.py
@@ -29,7 +29,7 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
from PIL import Image
import sprite_gen.frames.extract as extract
-from sprite_gen.spec.runio import load_request
+from sprite_gen.spec.runio import REQUEST_FILENAME, load_request
def _prepare_work_dir(source: Path, work: Path, states: list[str], align_x: str) -> None:
@@ -38,7 +38,7 @@ def _prepare_work_dir(source: Path, work: Path, states: list[str], align_x: str)
fit = dict(request.get("fit") or {})
fit["align_x"] = align_x
request["fit"] = fit
- (work / "sprite-request.json").write_text(
+ (work / REQUEST_FILENAME).write_text(
json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
)
for state in states:
diff --git a/sprite_gen/compose/compose_cycle.py b/sprite_gen/compose/compose_cycle.py
index df35c4e..edc5fde 100644
--- a/sprite_gen/compose/compose_cycle.py
+++ b/sprite_gen/compose/compose_cycle.py
@@ -17,7 +17,7 @@ from pathlib import Path
from PIL import Image, ImageDraw
from sprite_gen.util.cli_kwargs import namespace_from_kwargs
-from sprite_gen.curate.curation import apply_pixel_edits, apply_transform, frame_variant, load_curation, pixel_snap_scale, source_frame_index, state_pixel_ops, state_plan
+from sprite_gen.curate.curation import CURATION_FILENAME, apply_pixel_edits, apply_transform, frame_variant, load_curation, pixel_snap_scale, source_frame_index, state_pixel_ops, state_plan
from sprite_gen.spec.layout import row_frame_rel, state_frame_total
from sprite_gen.frames.extract import require_frames_manifest
from sprite_gen.qa.preview import flatten
@@ -154,7 +154,7 @@ def _run_guarded(args, run_dir):
"name": args.name,
"selected_user_frames": user_frames,
"selected_zero_based_frames": [frame - 1 for frame in user_frames],
- "selection_source": "explicit-frames" if args.frames is not None else "curation.json",
+ "selection_source": "explicit-frames" if args.frames is not None else CURATION_FILENAME,
"transforms_applied": {str(n - 1): transforms[n - 1] for n in user_frames if (n - 1) in transforms},
"duration_ms": duration_ms,
"delay_ticks": round(duration_ms / 10),
diff --git a/sprite_gen/curate/curation.py b/sprite_gen/curate/curation.py
index bbe51e6..3a7ae4b 100644
--- a/sprite_gen/curate/curation.py
+++ b/sprite_gen/curate/curation.py
@@ -159,7 +159,7 @@ from typing import Any
from PIL import Image
from sprite_gen.spec.layout import raw_rel
-from sprite_gen.spec.runio import load_request
+from sprite_gen.spec.runio import REQUEST_FILENAME, load_request
from sprite_gen.util.resample import transform_cell
CURATION_FILENAME = "curation.json"
@@ -629,7 +629,7 @@ def run_revision(run_dir: Path) -> str:
stamped for a prior generation is detected as stale. Single source of run identity for
the server, compose, export, and the webview."""
h = hashlib.sha256()
- for name in ("sprite-request.json", "frames/frames-manifest.json"):
+ for name in (REQUEST_FILENAME, "frames/frames-manifest.json"):
try:
h.update((run_dir / name).read_bytes())
except OSError:
diff --git a/sprite_gen/frames/extract.py b/sprite_gen/frames/extract.py
index 77ba6f8..7ec8c3f 100644
--- a/sprite_gen/frames/extract.py
+++ b/sprite_gen/frames/extract.py
@@ -20,7 +20,7 @@ from PIL import Image, ImageChops
from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen._deps import np
-from sprite_gen.curate.curation import effective_logical_height, pixel_snap_scale
+from sprite_gen.curate.curation import CURATION_FILENAME, effective_logical_height, pixel_snap_scale
from sprite_gen.spec.layout import frames_dir_rel, raw_rel, take_raw_rel
from sprite_gen.spec.runio import (REQUEST_FILENAME, acquire_run_dir_lock, atomic_save_image,
atomic_write_text, load_request, publish_guard, relative_posix,
@@ -3236,7 +3236,7 @@ def _run_locked(args: argparse.Namespace, run_dir: Path):
if effective_chroma != chroma_config:
request["chroma"] = effective_chroma
atomic_write_text(
- run_dir / "sprite-request.json",
+ run_dir / REQUEST_FILENAME,
json.dumps(request, ensure_ascii=False, indent=2) + "\n",
)
states = list(request["states"]) if args.states == "all" else [state.strip() for state in args.states.split(",") if state.strip()]
@@ -3850,7 +3850,7 @@ def heal_run(run_dir: Path | str) -> dict[str, Any]:
# 재유도하지 않는다 (회귀: 서버 가동 중 엔진 편집 → heal 이 확정 down_idle 을
# 재양자화해 드리프트). 해제는 사용자가 frozen 을 끄는 것뿐 — 관측 노트로 남긴다.
frozen: set[str] = set()
- curation_path = run_dir / "curation.json"
+ curation_path = run_dir / CURATION_FILENAME
if curation_path.is_file():
try:
cur_states = json.loads(curation_path.read_text(encoding="utf-8")).get("states", {})
diff --git a/sprite_gen/frames/unpack_atlas.py b/sprite_gen/frames/unpack_atlas.py
index 62cd61d..b2b9d01 100644
--- a/sprite_gen/frames/unpack_atlas.py
+++ b/sprite_gen/frames/unpack_atlas.py
@@ -38,6 +38,7 @@ from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.curate.curation import imported_ref_role
from sprite_gen.spec.runio import (
LOCK_FILENAME,
+ REQUEST_FILENAME,
acquire_run_dir_lock,
atomic_save_image,
atomic_write_text,
@@ -254,7 +255,7 @@ def write_run(
"chroma_key": provenance.get("chroma_key", {"name": MAGENTA, "hex": format_hex(KEY_TARGETS[MAGENTA]), "rgb": list(KEY_TARGETS[MAGENTA])}),
"states": request_states,
}
- atomic_write_text(out_dir / "sprite-request.json", json.dumps(request, ensure_ascii=False, indent=2) + "\n")
+ atomic_write_text(out_dir / REQUEST_FILENAME, json.dumps(request, ensure_ascii=False, indent=2) + "\n")
atomic_write_text(
frames_root / "frames-manifest.json",
json.dumps({"ok": True, "engine": "component-row", "run_dir": str(run_dir), "cell": request["cell"], "rows": manifest_rows, "errors": [], "warnings": []}, ensure_ascii=False, indent=2) + "\n",
@@ -374,7 +375,7 @@ def import_png_groups(out_dir: Path, groups: list[dict[str, Any]], iso: dict[str
}
if iso:
request["iso"] = iso # ground-grid geometry for the curator overlay
- atomic_write_text(out_dir / "sprite-request.json", json.dumps(request, ensure_ascii=False, indent=2) + "\n")
+ atomic_write_text(out_dir / REQUEST_FILENAME, json.dumps(request, ensure_ascii=False, indent=2) + "\n")
atomic_write_text(
out_dir / "frames" / "frames-manifest.json",
json.dumps({"ok": True, "engine": "component-row", "run_dir": str(run_dir), "cell": request["cell"],
diff --git a/sprite_gen/gen/gen_set.py b/sprite_gen/gen/gen_set.py
index e713d49..0e5edae 100644
--- a/sprite_gen/gen/gen_set.py
+++ b/sprite_gen/gen/gen_set.py
@@ -37,7 +37,7 @@ from sprite_gen import gen as gen_mod
from sprite_gen.curate import anchor as anchor_mod
from sprite_gen.gen.base import ask_codex_unavailable, child_asked, codex_unavailable_question, run_logged
from sprite_gen.spec import layout
-from sprite_gen.spec.runio import atomic_write_text
+from sprite_gen.spec.runio import REQUEST_FILENAME, atomic_write_text
from sprite_gen.util.console import utf8_streams
DEFAULT_CONCURRENCY = 6 # lead-verified 2026-08 (no provider throttling at 6-wide); serial one-by-one is the anti-pattern
@@ -224,7 +224,7 @@ def run_set(
) -> dict[str, Any]:
gen_runner = gen_runner or run_gen_cli
run_dir = run_dir.expanduser().resolve()
- if not (run_dir / "sprite-request.json").is_file():
+ if not (run_dir / REQUEST_FILENAME).is_file():
raise SystemExit(f"gen-set: {run_dir} is not a prepared run (no sprite-request.json) — run `sprite-gen prepare` first")
request = anchor_mod.load_request(run_dir)
ordered = _row_states(request, states)
diff --git a/sprite_gen/gen/pixel_grid.py b/sprite_gen/gen/pixel_grid.py
index d971a07..a8dc598 100644
--- a/sprite_gen/gen/pixel_grid.py
+++ b/sprite_gen/gen/pixel_grid.py
@@ -42,11 +42,12 @@ from PIL import Image
from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.util.hexcolor import parse_hex
+from .base import PNG_MAGIC
+
FORMATS = ("chargrid", "json")
KEYS = string.ascii_lowercase + string.ascii_uppercase + string.digits
TRANSPARENT_KEY = "."
HEX = re.compile(r"^#[0-9A-Fa-f]{6}$")
-PNG_MAGIC = b"\x89PNG\r\n\x1a\n"
PREVIEW_COLUMNS = 8 # frames a preview row holds before the next row
# PICO-8's 16 colours (lexaloffle.com/pico-8.php, the fixed palette of the console).
diff --git a/sprite_gen/gen/prepare.py b/sprite_gen/gen/prepare.py
index 594370b..acd52aa 100644
--- a/sprite_gen/gen/prepare.py
+++ b/sprite_gen/gen/prepare.py
@@ -25,6 +25,7 @@ from sprite_gen.curate.anchor import anchor_ref_rel
from sprite_gen.frames.cutout import GREEN, KEY_TARGETS, MAGENTA
from sprite_gen.frames.extract import color_distance
from sprite_gen.spec.layout import TAXONOMY, guide_rel, prompt_rel, raw_rel
+from sprite_gen.spec.runio import REQUEST_FILENAME
from sprite_gen.spec.subject import SUBJECTS
from sprite_gen.video import body_plan as body_mod
from sprite_gen.video.body_plan import Body
@@ -1122,7 +1123,7 @@ def _run(args: argparse.Namespace):
(out_dir / "references" / "generation-plan.json").write_text(
json.dumps(plan, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
- (out_dir / "sprite-request.json").write_text(
+ (out_dir / REQUEST_FILENAME).write_text(
json.dumps(request, ensure_ascii=False, indent=2) + "\n",
encoding="utf-8",
)
diff --git a/sprite_gen/qa/correction_loop.py b/sprite_gen/qa/correction_loop.py
index 190de58..b5c6ccd 100644
--- a/sprite_gen/qa/correction_loop.py
+++ b/sprite_gen/qa/correction_loop.py
@@ -16,7 +16,7 @@ from typing import Any
from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.qa import inspect as inspect_mod
from sprite_gen.qa import score as score_mod
-from sprite_gen.spec.runio import LOCK_FILENAME, atomic_write_text, refuse_overlap, relative_posix, same_folder
+from sprite_gen.spec.runio import LOCK_FILENAME, REQUEST_FILENAME, atomic_write_text, refuse_overlap, relative_posix, same_folder
from sprite_gen.util.console import utf8_streams
BEST_CANDIDATE = "best-candidate"
@@ -198,7 +198,7 @@ def run_loop(
)
if completed.returncode != 0:
raise SystemExit(f"provider command failed with exit {completed.returncode}: {command}")
- if not (next_run_dir / "sprite-request.json").is_file():
+ if not (next_run_dir / REQUEST_FILENAME).is_file():
raise SystemExit(f"provider command did not create a sprite-gen run dir: {next_run_dir}")
current = next_run_dir