Skip to content

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

5.8 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Build motion-QA previews for a sprite-gen run.

For each state in frames/frames-manifest.json this writes:
  qa/<state>-contact.png  - frames left-to-right on a checker so motion is readable
  qa/<state>.gif          - frames played at the state fps (loops)
  qa/all-contact.png      - every state stacked, one row per state

These are QA instruments, not runtime assets. The runtime SSoT stays
manifest.json.frame_layout over sprite-sheet-alpha.png.
"""

from __future__ import annotations

import argparse
import json
from pathlib import Path

from PIL import Image

from sprite_gen.util.cli_kwargs import namespace_from_kwargs
from sprite_gen.frames.extract import require_frames_manifest
from sprite_gen.spec.runio import REQUEST_FILENAME, load_request, read_guard
from sprite_gen.util.gif_utils import delay_ticks_to_duration_ms, save_clean_gif
from sprite_gen.util.console import utf8_streams


def checker(size: tuple[int, int], square: int = 16) -> Image.Image:
    """Neutral checker so transparent pixels and stray fringe are both visible. The one checker of
    sprite-gen's previews: these contact sheets, `compose-gif`'s and `compose-cycle`'s, and
    `pixel-draw`'s pick sheet."""
    w, h = size
    bg = Image.new("RGBA", size, (210, 210, 210, 255))
    px = bg.load()
    for y in range(h):
        for x in range(w):
            if ((x // square) + (y // square)) % 2 == 0:
                px[x, y] = (235, 235, 235, 255)
    return bg


def flatten(frame: Image.Image) -> Image.Image:
    base = checker(frame.size)
    base.alpha_composite(frame.convert("RGBA"))
    return base.convert("RGB")


def load_frames(run_dir: Path, files: list[str]) -> list[Image.Image]:
    return [Image.open(run_dir / rel).convert("RGBA") for rel in files]


def contact_sheet(frames: list[Image.Image], gap: int = 4) -> Image.Image:
    cw = max(f.width for f in frames)
    ch = max(f.height for f in frames)
    n = len(frames)
    sheet = Image.new("RGB", (n * cw + (n + 1) * gap, ch + 2 * gap), (255, 255, 255))
    x = gap
    for f in frames:
        sheet.paste(flatten(f), (x, gap))
        x += cw + gap
    return sheet


def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--run-dir", required=True, type=Path)
    parser.add_argument(
        "--delay-ticks",
        type=int,
        help="override every GIF preview delay in 1/100 second ticks",
    )
    return parser


def _run(args: argparse.Namespace):

    run_dir = args.run_dir.expanduser().resolve()
    # Read the manifest + request + frame tree under one shared read_guard, so a concurrent publish
    # swap never lets preview observe a mid-swap state (a missing/partial generation). Reader
    # isolation, same contract as serve/inspect (runio.read_guard ↔ publish_guard).
    with read_guard(run_dir):
        return _run_guarded(args, run_dir)


def _run_guarded(args, run_dir):
    manifest = require_frames_manifest(run_dir)  # fail loud if absent/corrupt
    # 읽기는 게이트 경유 (`load_request`) — raw 로 읽으면 은퇴 키 런에서 이관이 비껴간다.
    # 이 소비자는 request 없는 런도 허용하므로 부재만 관용한다 (게이트는 부재에 fail-loud).
    request_path = run_dir / REQUEST_FILENAME
    request = load_request(run_dir) if request_path.is_file() else {}
    state_meta = request.get("states", {})

    qa_dir = run_dir / "qa"
    qa_dir.mkdir(parents=True, exist_ok=True)

    summary = []
    state_sheets: list[tuple[str, Image.Image]] = []
    for row in manifest.get("rows", []):
        state = row["state"]
        files = row.get("files", [])
        if not files:
            summary.append({"state": state, "ok": False, "note": "no frame files"})
            continue
        frames = load_frames(run_dir, files)
        fps = int(state_meta.get(state, {}).get("fps", 6)) or 6
        loop = bool(state_meta.get(state, {}).get("loop", True))

        sheet = contact_sheet(frames)
        sheet.save(qa_dir / f"{state}-contact.png")
        state_sheets.append((state, sheet))

        duration = (
            delay_ticks_to_duration_ms(args.delay_ticks)
            if args.delay_ticks
            else max(1, round(1000 / fps))
        )
        save_clean_gif(
            frames,
            qa_dir / f"{state}.gif",
            duration_ms=duration,
            loop=0 if loop else 1,
        )
        summary.append(
            {
                "state": state,
                "ok": True,
                "frames": len(frames),
                "fps": fps,
                "delay_ticks": round(duration / 10),
                "loop": loop,
            }
        )

    # stacked all-state contact sheet
    if state_sheets:
        gap = 8
        width = max(s.width for _, s in state_sheets) + 2 * gap
        height = sum(s.height for _, s in state_sheets) + gap * (len(state_sheets) + 1)
        stacked = Image.new("RGB", (width, height), (255, 255, 255))
        y = gap
        for _state, s in state_sheets:
            stacked.paste(s, (gap, y))
            y += s.height + gap
        stacked.save(qa_dir / "all-contact.png")

    # Any per-state failure makes the whole preview fail loud — never a top-level ok:true over a
    # broken state (No Silent Fallback). The complete-generation gate above already rejects a
    # missing/empty generation; this guards the residual per-state paths.
    all_ok = bool(summary) and all(s.get("ok") for s in summary)
    print(json.dumps({"ok": all_ok, "qa_dir": str(qa_dir), "states": summary}, ensure_ascii=False, indent=2))
    return 0 if all_ok else 1



def run(**kwargs: object):
    return _run(namespace_from_kwargs(_build_parser(), kwargs))

def main() -> int:
    utf8_streams()
    parser = _build_parser()
    args = parser.parse_args()
    return _run(args)


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