Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
# SPDX-License-Identifier: Apache-2.0
"""Takes 1급 계약 + 파생 캐시 자가치유(heal_run).
- 한 상태의 프레임 풀 = primary raw + 선언된 테이크들(`states.<s>.takes`),
각 스트립은 독립 스냅(스트립별 합의 피치), 행 정합·배치는 함께.
- frames/ 는 (raw + request + 엔진)의 파생 캐시 — 행의 engine_revision 이 현재
엔진과 다르면 heal_run 이 raw 에서 자동 재유도한다. 뷰에 '재추출' 개념이
없는 실시간 계약(maintainer 확정 2026-07-14)의 엔진 반쪽이다.
"""
import json
import random
from pathlib import Path
import pytest
from PIL import Image
import sprite_gen.frames.extract as extract_module
from sprite_gen.spec.layout import take_raw_rel
MAGENTA = (255, 0, 255)
def _logical_art(width, height, seed):
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 _strip(frames, seed, pitch=8, logical=(20, 36), gap=40):
frame = _logical_art(*logical, seed=seed).resize(
(logical[0] * pitch, logical[1] * pitch), Image.Resampling.NEAREST)
strip = Image.new("RGB", (frame.width * frames + gap * (frames + 1), frame.height + gap * 2), MAGENTA)
for i in range(frames):
strip.paste(frame, (gap + i * (frame.width + gap), gap))
return strip
def _build_run(root: Path, takes=None) -> Path:
run_dir = root / "run"
(run_dir / "raw").mkdir(parents=True)
_strip(2, seed=7).save(run_dir / "raw" / "walk.png")
request = {
"version": 1,
"kind": "sprite-gen-request",
"engine": "component-row",
"character": {"id": "takebot", "description": "takes fixture", "base_image": None},
"cell": {"shape": "square", "width": 96, "height": 96, "safe_margin_x": 8,
"safe_margin_y": 8, "size": 96, "safe_margin": 8},
"chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255], "selection": "fallback"},
"states": {"walk": {"frames": 2, "fps": 8, "loop": True, "action": "takes fixture"}},
"fit": {"pixel_unfake": True, "logical_height": 48},
}
if takes is not None:
request["states"]["walk"]["takes"] = takes
(run_dir / "sprite-request.json").write_text(
json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
return run_dir
def _manifest(run_dir: Path) -> dict:
return json.loads((run_dir / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))
@pytest.mark.slow
def test_takes_extend_row_pool(tmp_path: Path) -> None:
takes = [{"label": "alt", "frames": 2}]
run_dir = _build_run(tmp_path, takes=takes)
request = json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
take_path = run_dir / take_raw_rel(request, "walk", "alt")
take_path.parent.mkdir(parents=True)
_strip(2, seed=11).save(take_path)
assert extract_module.run(run_dir=run_dir) == 0
row = _manifest(run_dir)["rows"][0]
assert row["frames"] == 4
assert len(row["files"]) == 4
assert row["labels"] == ["", "", "alt#0", "alt#1"]
assert row["takes"] == [
{"label": None, "start": 0, "frames": 2, "raw": "raw/walk.png"},
{"label": "alt", "start": 2, "frames": 2, "raw": "raw/walk.takes/alt.png"},
]
for rel in row["files"]:
assert (run_dir / rel).is_file(), rel
# 테이크 프레임은 다른 생성물이다 — primary 프레임과 내용이 달라야 한다
primary = Image.open(run_dir / row["files"][0]).tobytes()
alt = Image.open(run_dir / row["files"][2]).tobytes()
assert primary != alt
def test_take_raw_missing_fails_loud(tmp_path: Path) -> None:
run_dir = _build_run(tmp_path, takes=[{"label": "alt", "frames": 2}])
assert extract_module.run(run_dir=run_dir) == 1 # 선언된 테이크 누락 = 행 실패 (부분 풀 게시 금지)
assert not (run_dir / "frames" / "frames-manifest.json").is_file()
def test_takes_require_pixel_perfect(tmp_path: Path) -> None:
run_dir = _build_run(tmp_path, takes=[{"label": "alt", "frames": 2}])
request = json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
del request["fit"]["pixel_unfake"]
(run_dir / "sprite-request.json").write_text(json.dumps(request), encoding="utf-8")
take_path = run_dir / take_raw_rel(request, "walk", "alt")
take_path.parent.mkdir(parents=True)
_strip(2, seed=11).save(take_path)
assert extract_module.run(run_dir=run_dir) == 1
def test_heal_keeps_stale_row_without_raw(tmp_path: Path) -> None:
run_dir = _build_run(tmp_path)
assert extract_module.run(run_dir=run_dir) == 0
manifest_path = run_dir / "frames" / "frames-manifest.json"
manifest = _manifest(run_dir)
manifest["rows"][0]["engine_revision"] = "0" * 12
manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
frame_bytes = (run_dir / "frames" / "walk" / "frame-0.png").read_bytes()
(run_dir / "raw" / "walk.png").unlink()
report = extract_module.heal_run(run_dir)
assert report["healed"] == []
assert report["kept_stale"] == ["walk"]
assert report["notes"]
# 재료가 없으면 이전 세대를 바이트 그대로 보존한다
assert (run_dir / "frames" / "walk" / "frame-0.png").read_bytes() == frame_bytes
@pytest.mark.slow
def test_view_heals_and_downloads_live_state(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
"""뷰/다운로드 계약: 스냅샷 요청이 stale 캐시를 자가치유하고, 버튼 3종은
현재 라이브 상태를 계산해 zip 으로 내려준다 (게임 적용 의미 없음)."""
import io
import zipfile
run_dir = _build_run(tmp_path)
assert extract_module.run(run_dir=run_dir) == 0
manifest_path = run_dir / "frames" / "frames-manifest.json"
manifest = _manifest(run_dir)
manifest["rows"][0]["engine_revision"] = "0" * 12
manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
import sprite_gen.serve.serve_curation as serve_curation
# 결정론: 그레이스를 넉넉히 주입해 느린 CI 러너(관측: Python 3.10)에서도 소규모
# heal 이 동기 경로로 완료됨을 안정 검증한다. 프로덕션 그레이스(1.5s)는 무변 —
# 벽시계 1.5s 에 의존하던 flaky 실패 제거 (validator 2026-07-21, heal 로직 무변).
monkeypatch.setattr(serve_curation, "_HEAL_GRACE_SECONDS", 60.0)
busy = serve_curation.maybe_heal(run_dir)
assert busy is False # 소규모 heal 은 그레이스 안에 끝나 동기 경로 유지
heal = serve_curation.take_heal_report() # 단일 소비자 (/api/run 역할)
assert heal is not None and heal["healed"] == ["walk"]
assert serve_curation.maybe_heal(run_dir) is False # 신선하면 no-op
assert serve_curation.take_heal_report() is None
built = serve_curation.build_download(run_dir, "atlas")
assert not isinstance(built, dict), built
data, filename = built
assert filename == "takebot-atlas.zip"
names = set(zipfile.ZipFile(io.BytesIO(data)).namelist())
assert names == {"sprite-sheet-alpha.png", "manifest.json"}
built = serve_curation.build_download(run_dir, "gifs")
assert not isinstance(built, dict), built
data, filename = built
assert filename == "takebot-gifs.zip"
assert any(n.endswith("walk.gif") for n in zipfile.ZipFile(io.BytesIO(data)).namelist())
# 줄 단위 단건 GIF — zip 이 아니라 GIF 원파일, 미지 상태는 fail loud
built = serve_curation.build_download(run_dir, "gif:walk")
assert not isinstance(built, dict), built
data, filename = built
assert filename == "takebot-walk.gif"
assert data[:6] in (b"GIF87a", b"GIF89a")
assert isinstance(serve_curation.build_download(run_dir, "gif:nope"), dict)
def test_atlas_reuses_cells_for_identical_instances(tmp_path: Path) -> None:
"""아틀라스 셀 재사용 (maintainer 승인 2026-07-16): 같은 (원본, 변형, 픽셀편집)의
복제 인스턴스는 칸 하나를 공유한다 — 루프딜레이용 프레임 복제가 텍스처를
늘리지 않는다. rect 는 재생 순서대로 반복되고, durations_ms 계약이 실린다."""
import sprite_gen.compose.compose_atlas as compose_module
run_dir = _build_run(tmp_path)
assert extract_module.run(run_dir=run_dir) == 0
# 프레임 0 을 두 번 복제(인스턴스 2, 3): 하나는 동일 굽기(재사용), 하나는 변형(별도 칸)
curation = {
"version": 1, "kind": "sprite-gen-curation",
"states": {"walk": {
"selected": [0, 1, 2, 3],
"clones": {"2": 0, "3": 0},
"transforms": {"3": {"rotate": 0, "scale": 1, "dx": 3, "dy": 0,
"shx": 0, "shy": 0, "flipX": 0}},
}},
}
from sprite_gen.curate.curation import stamp_curation
stamped = stamp_curation(run_dir, curation) # 세대 도장 없는 사이드카는 드롭된다 (정상 쓰기 경로)
(run_dir / "curation.json").write_text(json.dumps(stamped), encoding="utf-8")
assert compose_module.run(run_dir=run_dir, min_used_pixels=100) == 0
manifest = json.loads((run_dir / "manifest.json").read_text(encoding="utf-8"))
rects = manifest["frame_layout"]["rows"]["walk"]
assert len(rects) == 4
assert rects[2] == rects[0] # 동일 굽기 복제 = 같은 칸 재사용
assert rects[3] != rects[0] # 변형이 다르면 별도 칸
unique = {(r["x"], r["y"]) for r in rects}
assert len(unique) == 3
# 아틀라스 폭 = 고유 칸 수 (인스턴스 수 아님)
assert manifest["frame_layout"]["sheetWidth"] == 3 * manifest["frame_layout"]["cellWidth"]
anim = manifest["animation"]["rows"]["walk"]
assert anim["frames"] == 4
assert anim["durations_ms"] == [round(1000 / anim["fps"])] * 4
@pytest.mark.slow
def test_heal_isolates_failures_per_state(tmp_path: Path) -> None:
"""상태별 격리 (2026-07-22): 한 행의 재추출 실패가 다른 행의 스왑을 막지도,
failed 보고에 연좌시키지도 않는다 (회귀 synthetic_fixture_a — 6행 실패가 33행
전체를 "재계산 실패"로 묶었다)."""
run_dir = _build_run(tmp_path)
request = json.loads((run_dir / "sprite-request.json").read_text(encoding="utf-8"))
request["states"]["jump"] = {"frames": 2, "fps": 8, "loop": False, "action": "isolation fixture"}
(run_dir / "sprite-request.json").write_text(
json.dumps(request, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
_strip(2, seed=23).save(run_dir / "raw" / "jump.png")
assert extract_module.run(run_dir=run_dir) == 0
manifest_path = run_dir / "frames" / "frames-manifest.json"
manifest = _manifest(run_dir)
for row in manifest["rows"]:
row["engine_revision"] = "0" * 12
manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
jump_bytes = (run_dir / "frames" / "jump" / "frame-0.png").read_bytes()
# jump 재료를 컴포넌트 없는 전면 크로마로 바꿔 재추출이 실패하게 만든다
Image.new("RGB", (400, 160), MAGENTA).save(run_dir / "raw" / "jump.png")
report = extract_module.heal_run(run_dir)
assert report["healed"] == ["walk"]
assert report["failed"] == ["jump"]
assert any("jump" in note for note in report["notes"])
rows = {row["state"]: row for row in _manifest(run_dir)["rows"]}
# 통과 행은 새 엔진으로 스왑, 실패 행은 이전 세대 바이트 그대로
assert rows["walk"]["engine_revision"] == extract_module.engine_revision()
assert rows["jump"]["engine_revision"] == "0" * 12
assert (run_dir / "frames" / "jump" / "frame-0.png").read_bytes() == jump_bytes
# durable evidence 는 실패 상태를 상태 단위로 유지한다 (재시도 차단 소재)
evidence = json.loads((run_dir / "extract-failure.json").read_text(encoding="utf-8"))
assert evidence["ok"] is False
assert any(str(error).startswith("jump:") for error in evidence["errors"])