Skip to content

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

14.9 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Scene specs: timing, placement defaults, planes and stride binding to the measured sequence."""

import hashlib
import json
from pathlib import Path

import pytest
from PIL import Image, ImageDraw

from sprite_gen.qa.motion import analyze_motion
from sprite_gen.scene import model
from sprite_gen.scene.model import bound_stride, load_scene, merge_fingerprints
from sprite_gen.spec import assets
from sprite_gen.spec.assets import load_asset


FOOT_BOX = (8, 25, 34, 12)


def sha(path):
    return hashlib.sha256(Path(path).read_bytes()).hexdigest()


def atlas(tmp_path):
    sheet = Image.new("RGBA", (48 * 5, 40))
    for index, x in enumerate((24, 22, 20, 18, 16)):
        draw = ImageDraw.Draw(sheet)
        draw.rectangle((48 * index + 15, 5, 48 * index + 30, 20), fill="white")
        draw.rectangle((48 * index + x, 30, 48 * index + x + 3, 32), fill="white")
    sheet.save(tmp_path / "atlas.png")
    rects = [{"x": 48 * i, "y": 0, "w": 48, "h": 40} for i in range(5)]
    path = tmp_path / "atlas.json"
    path.write_text(json.dumps({
        "sprite_sheet_alpha": "atlas.png",
        "frame_layout": {"rows": {"walk": rects, "idle": [rects[0]] * 5}},
        "animation": {"rows": {s: {"fps": 10, "durations_ms": [100] * 5, "loop": True} for s in ("walk", "idle")}},
    }))
    return path


def motion_report(tmp_path, name="walk.motion.json", **load):
    report = analyze_motion(load_asset(tmp_path / "atlas.json", **load), contacts="0:4", foot_box=FOOT_BOX)
    assert report["stride_verified"] is True
    path = tmp_path / name
    path.write_text(json.dumps(report))
    return path


def scene(tmp_path, layers=None, **overrides):
    spec = {"kind": "sprite-gen-scene", "version": 1, "canvas": {"width": 48, "height": 40, "background": [0, 0, 0]},
            "fps": 10, "duration": 0.5, "assets": {"walk": {"source": "atlas.json", "state": "walk"}},
            "layers": layers if layers is not None else [{"id": "hero", "asset": "walk", "at": [24, 40]}]}
    spec.update(overrides)
    path = tmp_path / "scene.json"
    path.write_text(json.dumps(spec))
    return path


def test_layers_carry_defaults_raster_size_and_z_order(tmp_path):
    atlas(tmp_path)
    loaded = load_scene(scene(tmp_path, layers=[
        {"id": "front", "asset": "walk", "at": [10, 40], "z": 5},
        {"id": "back", "asset": "walk", "at": [20, 40], "z": -1, "scale": 0.33, "opacity": 0.5, "loop": False},
    ], assets={"walk": {"source": "atlas.json", "state": "walk"}}))
    assert [layer.id for layer in loaded.layers] == ["back", "front"]
    front, back = loaded.layers[1], loaded.layers[0]
    assert front.velocity == (0, 0) and front.scale == 1 and front.raster_size == (48, 40)
    assert front.opacity == 1 and front.loop is True and front.plane is None and front.playback_rate == 1
    assert back.raster_size == (16, 13)
    assert back.opacity == 0.5 and back.loop is False
    assert loaded.frame_count == 5 and loaded.background == (0, 0, 0, 255)
    assert loaded.spec["canvas"]["background"] == [0, 0, 0]
    assert loaded.source_fingerprints == {str(p.resolve()): sha(p) for p in (tmp_path / "scene.json", tmp_path / "atlas.json", tmp_path / "atlas.png")}


def test_plane_velocity_adds_to_layer_velocity(tmp_path):
    atlas(tmp_path)
    loaded = load_scene(scene(tmp_path, planes={"ground": {"velocity": [-30, 0]}},
                              layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "velocity": [5, 2], "plane": "ground"}]))
    assert loaded.layers[0].velocity == (-25, 2)
    with pytest.raises(ValueError, match="unknown plane"):
        load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "plane": "sky"}]))


def test_stride_applies_actual_raster_scale_playback_rate_and_explicit_direction(tmp_path):
    atlas(tmp_path)
    report = motion_report(tmp_path, state="walk")
    speed = json.loads(report.read_text())["stride_px_per_second"]
    assert speed == pytest.approx(20)
    loaded = load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "scale": 0.33,
                                                 "playback_rate": 2, "stride": {"report": "walk.motion.json", "direction": "left"}}]))
    layer = loaded.layers[0]
    assert layer.raster_size == (16, 13)
    assert layer.velocity == (pytest.approx(-20 * (16 / 48) * 2), 0)
    assert layer.velocity[0] != pytest.approx(-20 * 0.33 * 2)
    assert loaded.source_fingerprints[str(report.resolve())] == sha(report)
    right = load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "at": [24, 40],
                                                "stride": {"report": "walk.motion.json", "direction": "right"}}]))
    assert right.layers[0].velocity == (pytest.approx(20), 0)


@pytest.mark.parametrize("case, message", [
    ("other-state", "another state, frame rate or anchor"),
    ("fps-override", "another state, frame rate or anchor"),
    ("anchor-override", "another state, frame rate or anchor"),
    ("unverified", "unverified"),
    ("stale-bytes", "stale or belongs to another asset"),
    ("no-identity", "lacks its sequence identity"),
    ("not-a-report", "sprite-gen-motion-report"),
])
def test_stride_rejects_reports_of_any_other_selection_of_the_same_files(tmp_path, case, message):
    atlas(tmp_path)
    if case == "other-state":
        report = motion_report(tmp_path, state="walk")
        spec = scene(tmp_path, assets={"walk": {"source": "atlas.json", "state": "idle"}},
                     layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "stride": {"report": report.name, "direction": "right"}}])
    else:
        load = {"state": "walk"}
        if case == "fps-override":
            load["fps"] = 5
        if case == "anchor-override":
            load["anchor"] = (24, 39)
        report = motion_report(tmp_path, **load)
        data = json.loads(report.read_text())
        if case == "unverified":
            data["stride_verified"] = False
        if case == "no-identity":
            del data["sequence"]
        if case == "not-a-report":
            data["kind"] = "sprite-gen-scene-inspection"
        report.write_text(json.dumps(data))
        if case == "stale-bytes":
            with Image.open(tmp_path / "atlas.png") as sheet:
                sheet.convert("RGBA").save(tmp_path / "atlas.png", optimize=True)
            assert sha(tmp_path / "atlas.png") != data["source_fingerprints"][str((tmp_path / "atlas.png").resolve())]
        spec = scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "stride": {"report": report.name, "direction": "right"}}])
    with pytest.raises(ValueError, match=message):
        load_scene(spec)


def test_stride_report_and_velocity_are_exclusive_and_direction_is_required(tmp_path):
    atlas(tmp_path)
    report = motion_report(tmp_path, state="walk")
    with pytest.raises(ValueError, match="not both"):
        load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "velocity": [1, 0], "stride": {"report": report.name, "direction": "right"}}]))
    with pytest.raises(ValueError, match="explicit left/right"):
        load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "stride": {"report": report.name}}]))
    with pytest.raises(ValueError, match="explicit left/right"):
        load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "stride": {"report": report.name, "direction": "up"}}]))
    with pytest.raises(ValueError, match="unknown stride fields"):
        load_scene(scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "stride": {"report": report.name, "direction": "right", "flip": True}}]))


def test_bound_stride_is_the_single_gate_for_measured_speed(tmp_path):
    atlas(tmp_path)
    walk = load_asset(tmp_path / "atlas.json", state="walk")
    report = json.loads(json.dumps(analyze_motion(walk, contacts="0:4", foot_box=FOOT_BOX)))
    assert bound_stride(report, walk) == pytest.approx(20)
    with pytest.raises(ValueError):
        bound_stride(report, load_asset(tmp_path / "atlas.json", state="idle"))
    with pytest.raises(ValueError):
        bound_stride({**report, "stride_px_per_second": 0}, walk)


def test_scene_and_report_identity_are_the_parsed_bytes(tmp_path, monkeypatch):
    atlas(tmp_path)
    report = motion_report(tmp_path, state="walk")
    spec = scene(tmp_path, layers=[{"id": "hero", "asset": "walk", "at": [24, 40], "stride": {"report": report.name, "direction": "right"}}])
    original_hashes = {str(p.resolve()): sha(p) for p in (spec, report)}
    original = model.read_json

    def read_then_rewrite(path):
        document, digest = original(path)
        Path(path).write_text(json.dumps(document, indent=4))
        return document, digest

    monkeypatch.setattr(model, "read_json", read_then_rewrite)
    loaded = load_scene(spec)
    for path, digest in original_hashes.items():
        assert loaded.source_fingerprints[path] == digest
        assert sha(path) != digest
    assert loaded.layers[0].velocity == (pytest.approx(20), 0)


def test_merge_fingerprints_keeps_one_digest_per_path_and_refuses_a_second_without_touching_the_map():
    known = {"/scene.json": "a", "/actor.png": "b"}
    assert merge_fingerprints(known, {"/actor.png": "b", "/atlas.png": "c"}) is known
    assert known == {"/scene.json": "a", "/actor.png": "b", "/atlas.png": "c"}
    with pytest.raises(ValueError, match=r"changed during load.*/actor\.png, /scene\.json"):
        merge_fingerprints(known, {"/report.json": "d", "/scene.json": "A", "/actor.png": "B"})
    assert known == {"/scene.json": "a", "/actor.png": "b", "/atlas.png": "c"}


def test_shared_asset_file_replaced_between_two_loads_is_refused(tmp_path, monkeypatch):
    actor = tmp_path / "actor.png"
    Image.new("RGBA", (4, 4), "red").save(actor)
    spec = scene(tmp_path, assets={"first": "actor.png", "second": "actor.png"},
                 layers=[{"id": "first", "asset": "first", "at": [12, 40]}, {"id": "second", "asset": "second", "at": [36, 40]}])
    original = assets._read_bytes
    reads = []

    def read_then_replace_once(path):
        data = original(path)
        if Path(path).name == "actor.png":
            reads.append(data)
            if len(reads) == 1:
                Image.new("RGBA", (4, 4), "blue").save(actor)
        return data

    monkeypatch.setattr(assets, "_read_bytes", read_then_replace_once)
    # Each asset's own snapshot is right; the scene must not attest to one file with two byte histories.
    with pytest.raises(ValueError, match=r"changed during load.*actor\.png"):
        load_scene(spec)
    assert len(reads) == 2 and reads[0] != reads[1]
    monkeypatch.undo()
    loaded = load_scene(spec)
    assert loaded.source_fingerprints[str(actor.resolve())] == sha(actor)
    assert loaded.assets["first"].fingerprints() == loaded.assets["second"].fingerprints() == {str(actor.resolve()): sha(actor)}


def test_stride_report_replaced_between_two_layers_reads_is_refused(tmp_path, monkeypatch):
    atlas(tmp_path)
    report = motion_report(tmp_path, state="walk")
    spec = scene(tmp_path, layers=[
        {"id": "left", "asset": "walk", "at": [12, 40], "stride": {"report": report.name, "direction": "left"}},
        {"id": "right", "asset": "walk", "at": [36, 40], "stride": {"report": report.name, "direction": "right"}},
    ])
    original = model.read_json
    digests = []

    def read_then_double_the_stride_once(path):
        document, digest = original(path)
        if Path(path) == report.resolve():
            digests.append(digest)
            if len(digests) == 1:
                report.write_text(json.dumps({**document, "stride_px_per_second": 2 * document["stride_px_per_second"]}))
        return document, digest

    monkeypatch.setattr(model, "read_json", read_then_double_the_stride_once)
    with pytest.raises(ValueError, match=r"changed during load.*walk\.motion\.json"):
        load_scene(spec)
    assert len(digests) == 2 and digests[0] != digests[1]
    # Both versions pass the per-report gate for this sequence; only the scene-wide map tells them apart.
    assert bound_stride(json.loads(report.read_text()), load_asset(tmp_path / "atlas.json", state="walk")) == pytest.approx(40)
    monkeypatch.undo()
    loaded = load_scene(spec)
    assert [layer.velocity for layer in loaded.layers] == [(pytest.approx(-40), 0), (pytest.approx(40), 0)]
    assert loaded.source_fingerprints[str(report.resolve())] == sha(report)


def test_unchanged_repeated_references_share_one_digest_per_path(tmp_path):
    atlas(tmp_path)
    Image.new("RGBA", (4, 4), "red").save(tmp_path / "actor.png")
    report = motion_report(tmp_path, state="walk")
    loaded = load_scene(scene(tmp_path, assets={"walk": {"source": "atlas.json", "state": "walk"}, "idle": {"source": "atlas.json", "state": "idle"},
                                                "first": "actor.png", "second": "actor.png"},
                              layers=[{"id": "left", "asset": "walk", "at": [12, 40], "stride": {"report": report.name, "direction": "left"}},
                                      {"id": "right", "asset": "walk", "at": [36, 40], "stride": {"report": report.name, "direction": "right"}},
                                      {"id": "still", "asset": "idle", "at": [24, 40]},
                                      {"id": "first", "asset": "first", "at": [8, 40]},
                                      {"id": "second", "asset": "second", "at": [40, 40]}]))
    assert loaded.source_fingerprints == {str((tmp_path / name).resolve()): sha(tmp_path / name)
                                          for name in ("scene.json", "atlas.json", "atlas.png", "actor.png", report.name)}
    by_id = {layer.id: layer for layer in loaded.layers}
    assert by_id["left"].velocity == (pytest.approx(-20), 0) and by_id["right"].velocity == (pytest.approx(20), 0)
    assert by_id["still"].velocity == by_id["first"].velocity == by_id["second"].velocity == (0, 0)


@pytest.mark.parametrize("overrides, message", [
    ({"kind": "scene"}, "kind sprite-gen-scene"),
    ({"extra": 1}, "unknown scene fields"),
    ({"duration": 0.55}, "integer"),
    ({"duration": 1e-10}, "integer"),
    ({"fps": 200, "duration": 1}, "fps <= 120"),
    ({"canvas": {"width": 48.5, "height": 40}}, "integer dimensions"),
    ({"canvas": {"width": 48, "height": 40, "background": [0, 0, 300]}}, "RGB or RGBA"),
    ({"assets": {}}, "nonempty"),
    ({"layers": []}, "nonempty"),
    ({"layers": [{"id": "hero", "asset": "walk"}, {"id": "hero", "asset": "walk"}]}, "unique"),
    ({"layers": [{"id": "hero", "asset": "ghost"}]}, "unknown asset"),
    ({"layers": [{"id": "hero", "asset": "walk", "opacity": 1.5}]}, "0..1"),
    ({"layers": [{"id": "hero", "asset": "walk", "repeat_x": True, "period": 49}]}, "within the source width"),
    ({"layers": [{"id": "hero", "asset": "walk", "repeat_x": "yes"}]}, "boolean"),
    ({"layers": [{"id": "hero", "asset": "walk", "scale": 0}]}, "positive"),
    ({"light": {"angle": 3}}, "unknown light fields"),
])
def test_invalid_scene_specs_are_rejected(tmp_path, overrides, message):
    atlas(tmp_path)
    with pytest.raises(ValueError, match=message):
        load_scene(scene(tmp_path, **overrides))