Skip to content

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

8.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""`fit.logical_height` 계약 — 선언값이 아니라 파생 격자가 진실이다.

회귀 (2026-07-25, 합성 회귀 hero synthetic fixtures): `conform`(눌림)이 제거된 뒤
`logical_height: 48` 은 셀 64 에서 아무 픽셀도 바꾸지 않는 값이 됐다 (`64//48 == 1`
== `64//64`). 그런데 남아서 두 가지를 오염시켰다:

1. 큐레이션 행 지문(`state_revision`)이 **선언값**을 물고 있어서, 그 죽은 값을 지우기만
   해도 프레임이 바이트 동일한데 14행 큐레이션이 통째로 드롭됐다.
2. 웹뷰 헤더가 "48px" 라고 거짓 라벨을 띄웠다 (실제 논리 높이는 64).

계약:
- `effective_logical_height` = 셀 높이 / 파생 배율. 정수 격자가 반올림한 결과가 진실.
- 행 지문은 파생 배율만 본다 — 출력이 같은 선언 편집은 큐레이션을 살린다.
- 선언이 적용되지 못하면 추출이 경고로 관측시킨다 (조용히 무시하지 않는다).
- 배율 식은 한 곳(`pixel_snap_scale`)만 소유한다 — extract·웹뷰가 손으로 복제하지 않는다.
"""
from __future__ import annotations

import json
import random
import re
from pathlib import Path

from PIL import Image

import sprite_gen.frames.extract as extract_module
from sprite_gen.curate.curation import (
    effective_logical_height,
    pixel_snap_scale,
    state_revision,
)

REPO_ROOT = Path(__file__).resolve().parents[2]
MAGENTA = (255, 0, 255)
CELL = 64


def _logical_art(width: int, height: int, seed: int) -> Image.Image:
    rng = random.Random(seed)
    art = Image.new("RGB", (width, height), MAGENTA)
    for y in range(height):
        for x in range(width):
            if rng.random() < 0.55:
                art.putpixel((x, y), (rng.randrange(30, 220), rng.randrange(30, 220),
                                      rng.randrange(30, 220)))
    return art


def _build_pp_run(root: Path, logical_height: int | None) -> Path:
    """셀 64 픽셀퍼펙트 런 (정수 피치로 확대한 논리 아트 2프레임)."""
    run_dir = root / "run"
    (run_dir / "raw").mkdir(parents=True)
    pitch = 8
    frame = _logical_art(20, 36, seed=11).resize((20 * pitch, 36 * pitch),
                                                 Image.Resampling.NEAREST)
    gap = 40
    strip = Image.new("RGB", (frame.width * 2 + gap * 3, frame.height + gap * 2), MAGENTA)
    strip.paste(frame, (gap, gap))
    strip.paste(frame, (frame.width + gap * 2, gap))
    strip.save(run_dir / "raw" / "walk.png")
    fit: dict = {"pixel_unfake": True}
    if logical_height is not None:
        fit["logical_height"] = logical_height
    request = {
        "version": 1, "kind": "sprite-gen-request", "engine": "component-row",
        "character": {"id": "lhbot", "description": "logical height fixture", "base_image": None},
        "cell": {"shape": "square", "width": CELL, "height": CELL, "size": CELL,
                 "safe_margin_x": 6, "safe_margin_y": 6, "safe_margin": 6},
        "chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255],
                       "selection": "fallback"},
        "states": {"walk": {"frames": 2, "fps": 8, "loop": True, "action": "synthetic"}},
        "fit": fit,
    }
    (run_dir / "sprite-request.json").write_text(json.dumps(request, ensure_ascii=False), encoding="utf-8")
    return run_dir


def _set_fit(run_dir: Path, fit: dict) -> None:
    path = run_dir / "sprite-request.json"
    request = json.loads(path.read_text(encoding="utf-8"))
    request["fit"] = fit
    path.write_text(json.dumps(request, ensure_ascii=False), encoding="utf-8")


def _request(cell: int, **fit) -> dict:
    return {
        "cell": {"shape": "square", "size": cell, "width": cell, "height": cell,
                 "safe_margin": 6, "safe_margin_x": 6, "safe_margin_y": 6},
        "fit": fit,
        "states": {"idle": {"frames": 4, "fps": 4}},
    }


def test_declaration_that_the_integer_grid_rounds_away_reports_the_effective_height():
    """셀 64 + 선언 48 = 배율 1 = 유효 논리 높이 64 (선언은 무효)."""
    assert pixel_snap_scale(_request(64, pixel_unfake=True, logical_height=48)) == 1
    assert effective_logical_height(_request(64, pixel_unfake=True, logical_height=48)) == 64
    # 생략 = 셀과 1:1 (권장 기본값)
    assert effective_logical_height(_request(64, pixel_unfake=True)) == 64


def test_a_real_declaration_still_scales():
    """약수 선언은 그대로 살아있다 — 청키 룩은 기능이지 레거시가 아니다."""
    assert pixel_snap_scale(_request(64, pixel_unfake=True, logical_height=32)) == 2
    assert effective_logical_height(_request(64, pixel_unfake=True, logical_height=32)) == 32
    assert pixel_snap_scale(_request(96, pixel_unfake=True, logical_height=32)) == 3
    assert effective_logical_height(_request(96, pixel_unfake=True, logical_height=32)) == 32


def test_legacy_run_without_pixel_perfect_has_no_logical_grid():
    assert pixel_snap_scale(_request(64)) is None
    assert effective_logical_height(_request(64)) is None


def test_row_fingerprint_survives_removing_a_dead_declaration(tmp_path: Path):
    """핵심 회귀: 출력이 같은 선언 편집은 행 지문을 바꾸지 않는다.

    이게 깨지면 죽은 값을 지우는 순간 큐레이션이 전량 드롭된다 (회귀 synthetic_fixture_b:
    프레임이 바이트 동일했는데도 14행이 통째로 날아갔다)."""
    run = _build_pp_run(tmp_path, logical_height=48)  # 셀 64 → 배율 1 → 선언 무효
    assert extract_module.run(run_dir=run) == 0
    frames_before = {p.name: p.read_bytes()
                     for p in sorted((run / "frames" / "walk").glob("frame-*.png"))}
    with_dead_value = state_revision(run, "walk")
    assert with_dead_value, "행 지문을 계산하지 못했다 — 픽스처 전제가 깨졌다"

    _set_fit(run, {"pixel_unfake": True})
    assert state_revision(run, "walk") == with_dead_value, (
        "무효 선언을 지웠을 뿐인데 행 지문이 바뀌었다 — 큐레이션이 통째로 드롭된다")

    # 전제 확인: 그 편집으로 프레임이 실제로 안 바뀐다 (지문 유지가 정당한 이유)
    assert extract_module.run(run_dir=run) == 0
    frames_after = {p.name: p.read_bytes()
                    for p in sorted((run / "frames" / "walk").glob("frame-*.png"))}
    assert frames_after == frames_before, "전제 붕괴: 선언 제거가 픽셀을 바꿨다"

    # 진짜로 격자를 바꾸는 선언은 지문을 바꿔야 한다 (검증이 무력화되면 안 된다)
    _set_fit(run, {"pixel_unfake": True, "logical_height": CELL // 2})
    assert state_revision(run, "walk") != with_dead_value, (
        "배율이 실제로 바뀌는 선언인데 지문이 그대로다 — 낡은 선택이 새 프레임에 적용된다")


def test_unhonored_declaration_is_reported_as_a_warning(tmp_path: Path):
    """조용히 무시하지 않는다 — 요청에 남은 죽은 값은 경고로 보인다 (원칙 6)."""
    run = _build_pp_run(tmp_path, logical_height=48)
    assert extract_module.run(run_dir=run) == 0
    manifest = json.loads((run / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
    warnings = " ".join(manifest.get("warnings") or [])
    assert "logical_height" in warnings and "not applied as declared" in warnings, (
        f"무효 선언이 관측되지 않았다: {manifest.get('warnings')}")

    # 유효한 선언은 경고하지 않는다 (경고가 노이즈가 되면 아무도 안 본다)
    quiet = _build_pp_run(tmp_path / "quiet", logical_height=CELL // 2)
    assert extract_module.run(run_dir=quiet) == 0
    quiet_manifest = json.loads(
        (quiet / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
    assert not any("not applied as declared" in w for w in (quiet_manifest.get("warnings") or [])), (
        f"유효한 선언에 경고가 붙었다: {quiet_manifest.get('warnings')}")


def test_scale_formula_has_a_single_owner():
    """extract·웹뷰가 배율 식을 손으로 복제하지 않는다 (원칙 1).

    복제본은 실제로 갈렸다 — 웹뷰 사본에는 usable-height 클램프 분기가 없었다."""
    formula = re.compile(r"cell(_state\[(.height.|Wire\.HEIGHT)\]|_height)\s*//\s*max\(1,\s*logical_height")
    for rel in ("sprite_gen/frames/extract.py", "sprite_gen/serve/serve_curation.py"):
        source = (REPO_ROOT / rel).read_text(encoding="utf-8")
        assert not formula.search(source), (
            f"{rel} 가 배율 식을 다시 유도한다 — pixel_snap_scale 을 호출해야 한다")
        assert "pixel_snap_scale" in source, f"{rel} 가 배율 SSoT 를 쓰지 않는다"