Skip to content

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

7.1 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Reroll a state's row as a NEW take — candidate pool, never a replacement.

리롤 = 같은 행을 한 번 더 생성해 **테이크로 병기**한다 (maintainer 2026-07-19 "리롤버튼
눌러서 후보군에 추가"). primary raw 는 건드리지 않고 `raw/<...>.takes/rerollN.png`
+ request `states.<state>.takes` 로 기록되므로, 추출 후 큐레이션 뷰에는 기존 프레임
뒤에 `rerollN#i` 라벨 후보가 이어 붙는다. 픽/기각은 사람 몫.

생성 refs 는 행 생성 계약(directional-anchor-workflow)을 따른다 — 결정은 `anchor.py`
하나가 소유한다 (`identity_ref`): 방향 런의 액션 행이면 그 방향 앵커를 큐레이션 진실에서
매번 다시 구워 붙이고, 앵커 행 자체/단순 런이면 `base-source.*` 를 붙인다. 여기에
레이아웃 가이드를 더한 두 장이 리롤 refs 다.

AI 개입은 raw 생성 한 곳 — 최종 프레임은 언제나 결정론 추출이 굽는다. 부분 추출은
없다 (공유 팔레트가 추출 배치 구성에 결합 — interpolate 와 같은 계약).
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path
from typing import Any

from sprite_gen.curate.anchor import identity_ref
from sprite_gen.spec.runio import load_request, write_request
from sprite_gen.gen import HARD_DEFAULT_PROVIDER, PROVIDERS, generate_image
from sprite_gen.spec.layout import guide_rel, prompt_rel, take_raw_rel
from sprite_gen.util.console import utf8_streams


def next_reroll_label(request: dict[str, Any], state: str) -> str:
    takes = request["states"][state].get("takes") or []
    used = set()
    for take in takes:
        m = re.fullmatch(r"reroll(\d+)", str(take.get("label") or ""))
        if m:
            used.add(int(m.group(1)))
    n = 1
    while n in used:
        n += 1
    return f"reroll{n}"


def record_take(run_dir: Path, state: str, label: str, frames: int) -> None:
    """request 의 takes 선언 갱신 (멱등) — write_take(interpolate)와 같은 기록 계약.

    Isolation: 생성이 수 분 걸리므로 시작 시점에 읽은 request 로 쓰면 그 사이의
    다른 변경(다른 행 리롤·fps 수정)을 덮어쓴다 (lost update). publish_guard
    배타락 안에서 **fresh 재독 → 갱신 → 원자 쓰기** 로만 기록한다."""
    from sprite_gen.spec.runio import publish_guard

    with publish_guard(run_dir):
        # 락 안 fresh 재독도 게이트를 통과한다 — 이관 판정·두 키 hard fail 이 한 곳에만 있어야
        # 한다. 게이트는 읽기만 하므로 락 안에서도 안전하다.
        fresh = load_request(run_dir)
        takes = fresh["states"][state].setdefault("takes", [])
        entry = next((t for t in takes if t.get("label") == label), None)
        if entry is None:
            takes.append({"label": label, "frames": frames})
        else:
            entry["frames"] = frames
        # 쓰기도 게이트 경유 (`write_request`): 테이크 기록은 스키마와 무관한 편집이라
        # 디스크의 키 형태를 그대로 둔다 (스키마 이관은 `sprite-gen migrate-request` 만).
        write_request(run_dir, fresh)


def reroll_state(run_dir: Path | str, state: str, provider: str = HARD_DEFAULT_PROVIDER,
                 label: str | None = None) -> Path:
    """행 리롤 한 번: 테이크 raw 생성 + request takes 기록. 반환 = 테이크 raw 경로."""
    run_dir = Path(run_dir)
    # 읽기는 **게이트만** 쓴다 (`load_request`): 여기서 raw 로 읽으면 아직 이관되지 않은
    # 레거시 런에서 아래 `fit.pixel_unfake` 검사가 항상 False 가 되어, 언페이크가 켜진 런의
    # 리롤을 "켜져 있지 않다" 며 거부한다 (validator 검증 2026-07-26 R1 재현). 리롤은 뷰가 **별도
    # 서브프로세스**로 띄우므로 뷰 프로세스의 in-memory 이관도 여기로 넘어오지 않는다.
    request = load_request(run_dir)
    if state not in request.get("states", {}):
        raise SystemExit(f"unknown state: {state}")
    label = label or next_reroll_label(request, state)
    if "/" in label or label.startswith("."):
        raise SystemExit(f"take label must be filesystem-safe: {label!r}")
    # 테이크는 pixel_unfake 추출 계약 위에서만 병합된다 — 생성비를 쓰기 전에 막는다
    # (실측 2026-07-19: 비-pp 런에서 생성까지 간 뒤 추출이 "takes require
    # fit.pixel_unfake" 로 죽었다 — fail-loud 는 맞지만 늦다).
    if not (request.get("fit") or {}).get("pixel_unfake"):
        raise SystemExit("reroll: takes require fit.pixel_unfake on this run "
                         "(candidate pool rides the take pipeline)")
    prompt_path = run_dir / prompt_rel(request, state)
    if not prompt_path.is_file():
        raise SystemExit(f"reroll: prompt file missing: {prompt_path}")
    refs = [identity_ref(run_dir, state, request=request)]
    guide_path = run_dir / guide_rel(request, state)
    if guide_path.is_file():
        refs.append(guide_path)
    target = run_dir / take_raw_rel(request, state, label)
    target.parent.mkdir(parents=True, exist_ok=True)
    generate_image(provider, prompt_path.read_text(encoding="utf-8"), target, refs=refs)
    frames = int(request["states"][state]["frames"])
    record_take(run_dir, state, label, frames)
    print(f"[reroll] take written: {target.relative_to(run_dir)} "
          f"(state={state}, frames={frames}, provider={provider})")
    return target


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--run-dir", required=True)
    parser.add_argument("--state", required=True)
    parser.add_argument("--provider", choices=PROVIDERS, default=HARD_DEFAULT_PROVIDER,
                        help="생성 백엔드 (기본 codex)")
    parser.add_argument("--label", default=None, help="테이크 라벨 (기본 rerollN 자동 증가)")
    parser.add_argument("--extract", action="store_true",
                        help="기록 후 전체 배치 재추출까지 수행 (부분 추출은 팔레트 배치 결합 때문에 지원하지 않음)")
    return parser


def main(argv: list[str] | None = None) -> int:
    utf8_streams()
    args = _build_parser().parse_args(argv)
    reroll_state(args.run_dir, args.state, provider=args.provider, label=args.label)
    if args.extract:
        from sprite_gen.frames import extract as extract_module
        code = extract_module.run(run_dir=Path(args.run_dir))
        if code != 0:
            return code
        print("[reroll] full-batch re-extraction done")
    else:
        # 인터프리터는 sys.executable 로 찍는다 — 이 힌트는 붙여넣어 바로 실행되는
        # 명령이고, 전역 `python3` 는 이 패키지의 의존(NumPy/Pillow)이 없는 다른
        # 인터프리터일 수 있다 (SKILL.md "실행 인터프리터" 게이트).
        print("[reroll] next: re-extract the FULL batch so the shared palette stays "
              f"consistent -> {sys.executable} -m sprite_gen.frames.extract --run-dir {args.run_dir}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())