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
"""The shared read-only adapter: real writer formats, one-read snapshots, bound fingerprints."""
import hashlib
import importlib
import json
from pathlib import Path
import pytest
from PIL import Image, ImageDraw
from conftest import run_script
from sprite_gen.spec import assets
from sprite_gen.spec.assets import FrameSequence, load_asset, same_identity, sequence_identity
from sprite_gen.video.loop import build_strip
def sha(path):
return hashlib.sha256(Path(path).read_bytes()).hexdigest()
def walk_frames(xs=(24, 22, 20, 18, 16)):
frames = []
for x in xs:
frame = Image.new("RGBA", (48, 40))
draw = ImageDraw.Draw(frame)
draw.rectangle((15, 5, 30, 20), fill="white")
draw.rectangle((x, 30, x + 3, y := 32), fill=(200, 40, 40, 255))
frames.append(frame)
return frames
def descriptor(tmp_path, *, anchor=None, durations=(0.1, 0.1, 0.1, 0.1, 0.1), files=None):
entries = []
for index, (frame, duration) in enumerate(zip(walk_frames(), durations)):
name = f"foot-{index}.png" if files is None else files[index]
path = tmp_path / name
if not path.exists():
frame.save(path)
entries.append({"file": name, "duration": duration})
data = {"kind": "sprite-gen-asset", "version": 1, "frames": entries}
if anchor is not None:
data["anchor"] = anchor
path = tmp_path / "walk.json"
path.write_text(json.dumps(data))
return path
def atlas(tmp_path, states=("walk", "idle")):
frames = walk_frames()
sheet = Image.new("RGBA", (48 * 5, 40))
for index, frame in enumerate(frames):
sheet.paste(frame, (48 * index, 0))
sheet.save(tmp_path / "atlas.png")
rects = [{"x": 48 * i, "y": 0, "w": 48, "h": 40} for i in range(5)]
rows = {"walk": rects, "idle": [rects[0]] * 3}
path = tmp_path / "atlas.json"
path.write_text(json.dumps({
"sprite_sheet_alpha": "atlas.png", "game_input": "atlas.png",
"frame_layout": {"rows": {s: rows[s] for s in states}},
"animation": {"rows": {s: {"fps": 10, "durations_ms": [100] * len(rows[s]), "loop": True} for s in states}},
}))
return path
def test_png_single_frame_defaults_to_one_second_and_bottom_centre(tmp_path):
source = tmp_path / "still.png"
walk_frames()[0].save(source)
seq = load_asset(source)
assert len(seq.frames) == 1 and seq.frames[0].mode == "RGBA"
assert seq.durations == (1.0,)
assert seq.anchor == (24.0, 40)
assert seq.metadata == {"source": str(source.resolve()), "anchor_source": "bottom-center default"}
assert seq.fingerprints() == {str(source.resolve()): sha(source)}
with pytest.raises(ValueError, match="state"):
load_asset(source, state="walk")
def test_descriptor_reads_ordered_frames_durations_anchor_and_every_file_hash(tmp_path):
source = descriptor(tmp_path, anchor=[12, 38], durations=(0.05, 0.15, 0.1, 0.1, 0.4))
seq = load_asset(source)
assert seq.durations == (0.05, 0.15, 0.1, 0.1, 0.4)
assert seq.duration == pytest.approx(0.8)
assert seq.anchor == (12.0, 38.0)
assert seq.metadata["anchor_source"] == "asset metadata"
expected = walk_frames()
for frame, original in zip(seq.frames, expected):
assert frame.tobytes() == original.tobytes()
assert seq.fingerprints() == {str((tmp_path / name).resolve()): sha(tmp_path / name)
for name in ["walk.json", *(f"foot-{i}.png" for i in range(5))]}
assert load_asset(source, anchor=(1, 2)).metadata["anchor_source"] == "explicit override"
with pytest.raises(ValueError, match="state"):
load_asset(source, state="walk")
def test_descriptor_referencing_one_file_twice_reads_it_once(tmp_path, monkeypatch):
source = descriptor(tmp_path, files=["a.png", "a.png", "b.png", "b.png", "b.png"])
reads = []
original = assets._read_bytes
def counting_read(path):
reads.append(Path(path).name)
return original(path)
monkeypatch.setattr(assets, "_read_bytes", counting_read)
seq = load_asset(source)
assert len(seq.frames) == 5
assert sorted(reads) == ["a.png", "b.png", "walk.json"]
assert set(seq.fingerprints()) == {str((tmp_path / n).resolve()) for n in ("walk.json", "a.png", "b.png")}
def test_real_loop_strip_writer_output_is_read_back_cell_by_cell(tmp_path):
frames = walk_frames()
strip, meta = build_strip(frames, cycle_seconds=0.5)
strip.save(tmp_path / "walk.strip.png")
(tmp_path / "walk.strip.json").write_text(json.dumps(meta))
seq = load_asset(tmp_path / "walk.strip.json")
assert seq.size == (meta["w"], meta["h"])
assert len(seq.frames) == meta["frames"]
assert seq.durations == (meta["delay_ms"] / 1000,) * meta["frames"]
assert seq.duration == pytest.approx(0.5)
assert seq.metadata["loop"] is True
assert seq.anchor == (meta["w"] / 2, meta["h"])
for index, frame in enumerate(seq.frames):
assert frame.tobytes() == strip.crop((index * meta["w"], 0, (index + 1) * meta["w"], meta["h"])).tobytes()
assert set(seq.fingerprints()) == {str((tmp_path / n).resolve()) for n in ("walk.strip.json", "walk.strip.png")}
with pytest.raises(ValueError, match="state"):
load_asset(tmp_path / "walk.strip.json", state="walk")
strip.crop((0, 0, strip.width - 1, strip.height)).save(tmp_path / "walk.strip.png")
with pytest.raises(ValueError, match="disagrees"):
load_asset(tmp_path / "walk.strip.json")
def test_real_runtime_atlas_writer_output_keeps_rects_and_timing(fixture_run_dir):
for script in ("extract_sprite_row_frames.py", "compose_sprite_atlas.py"):
proc = run_script(script, "--run-dir", str(fixture_run_dir))
assert proc.returncode == 0, proc.stdout + proc.stderr
manifest_path = fixture_run_dir / "manifest.json"
manifest = json.loads(manifest_path.read_text())
with pytest.raises(ValueError, match="--state is required"):
load_asset(manifest_path)
with pytest.raises(ValueError, match="unknown asset state"):
load_asset(manifest_path, state="fly")
with Image.open(fixture_run_dir / manifest["sprite_sheet_alpha"]) as sheet:
sheet = sheet.convert("RGBA")
for state, rects in manifest["frame_layout"]["rows"].items():
seq = load_asset(manifest_path, state=state)
timing = manifest["animation"]["rows"][state]
assert len(seq.frames) == len(rects)
assert seq.durations == tuple(ms / 1000 for ms in timing["durations_ms"])
assert seq.metadata["state"] == state
assert seq.metadata["loop"] is bool(timing["loop"])
for frame, rect in zip(seq.frames, rects):
assert frame.size == (rect["w"], rect["h"])
assert frame.tobytes() == sheet.crop((rect["x"], rect["y"], rect["x"] + rect["w"], rect["y"] + rect["h"])).tobytes()
assert seq.fingerprints() == {str(manifest_path.resolve()): sha(manifest_path),
str((fixture_run_dir / manifest["sprite_sheet_alpha"]).resolve()): sha(fixture_run_dir / manifest["sprite_sheet_alpha"])}
def test_fps_override_replaces_timing_and_is_part_of_identity(tmp_path):
source = atlas(tmp_path)
native = load_asset(source, state="walk")
faster = load_asset(source, state="walk", fps=5)
assert native.durations == (0.1,) * 5
assert faster.durations == (0.2,) * 5
assert faster.metadata["fps_override"] == 5.0
assert "fps_override" not in native.metadata
assert native.fingerprints() == faster.fingerprints()
assert sequence_identity(native) != sequence_identity(faster)
def test_identity_separates_states_rates_and_anchors_of_one_file_set(tmp_path):
source = atlas(tmp_path)
walk = load_asset(source, state="walk")
idle = load_asset(source, state="idle")
assert walk.fingerprints() == idle.fingerprints()
identity = json.loads(json.dumps(walk.identity()))
assert identity == {"source": str(source.resolve()), "state": "walk", "fps_override": None, "frame_count": 5,
"size": [48, 40], "anchor_px": [24.0, 40.0], "durations_seconds": [0.1] * 5}
assert same_identity(identity, walk)
assert not same_identity(identity, idle)
assert not same_identity(identity, load_asset(source, state="walk", fps=10.0001))
assert same_identity(identity, load_asset(source, state="walk", fps=10))
assert not same_identity(identity, load_asset(source, state="walk", anchor=(24, 39)))
assert not same_identity({**identity, "durations_seconds": [0.1] * 4 + [0.2]}, walk)
assert not same_identity({k: v for k, v in identity.items() if k != "state"}, walk)
assert not same_identity(None, walk)
def test_replacement_between_read_and_decode_cannot_separate_pixels_from_hash(tmp_path, monkeypatch):
source = tmp_path / "race.png"
Image.new("RGBA", (4, 4), "red").save(source)
red_hash = sha(source)
original = assets._read_bytes
def read_then_replace(path):
data = original(path)
Image.new("RGBA", (4, 4), "blue").save(path)
return data
monkeypatch.setattr(assets, "_read_bytes", read_then_replace)
loaded = load_asset(source)
assert loaded.frames[0].getpixel((0, 0)) == (255, 0, 0, 255)
assert loaded.fingerprints() == {str(source.resolve()): red_hash}
assert sha(source) != red_hash
def test_descriptor_identity_is_the_parsed_bytes(tmp_path, monkeypatch):
source = descriptor(tmp_path)
original_hash = sha(source)
original = assets._read_bytes
def read_then_edit(path):
data = original(path)
if Path(path).name == "walk.json":
edited = json.loads(data)
edited["frames"] = edited["frames"][:2]
Path(path).write_text(json.dumps(edited))
return data
monkeypatch.setattr(assets, "_read_bytes", read_then_edit)
loaded = load_asset(source)
assert len(loaded.frames) == 5
assert loaded.fingerprints()[str(source.resolve())] == original_hash
assert sha(source) != original_hash
def test_animated_and_oversized_images_are_refused_before_decoding(tmp_path, monkeypatch):
animated = tmp_path / "animated.png"
Image.new("RGBA", (4, 4), "red").save(animated, save_all=True, append_images=[Image.new("RGBA", (4, 4), "blue")], duration=50)
with pytest.raises(ValueError, match="animated"):
load_asset(animated)
monkeypatch.setattr(assets, "MAX_SOURCE_PIXELS", 15)
still = tmp_path / "still.png"
Image.new("RGBA", (4, 4)).save(still)
with pytest.raises(ValueError, match="exceeds the supported"):
load_asset(still)
monkeypatch.setattr(assets, "MAX_SOURCE_PIXELS", 16)
assert load_asset(still).size == (4, 4)
def test_frame_at_wraps_when_looping_and_holds_the_last_frame_otherwise(tmp_path):
seq = load_asset(descriptor(tmp_path, durations=(0.1, 0.2, 0.3, 0.1, 0.3)))
starts = [0, 0.1, 0.3, 0.6, 0.7]
for index, start in enumerate(starts):
assert seq.frame_at(start) is seq.frames[index]
assert seq.frame_at(start + 0.05) is seq.frames[index]
assert seq.frame_at(1.0) is seq.frames[0]
assert seq.frame_at(1.15) is seq.frames[1]
assert seq.frame_at(-0.05) is seq.frames[4]
assert seq.frame_at(1.0, loop=False) is seq.frames[4]
assert seq.frame_at(-1, loop=False) is seq.frames[0]
with pytest.raises(ValueError):
seq.frame_at(float("nan"))
@pytest.mark.parametrize("mutate, message", [
(lambda d: [1, 2], "must be an object"),
(lambda d: {**d, "frames": []}, "nonempty"),
(lambda d: {**d, "frames": [{"file": "foot-0.png"}]}, "duration"),
(lambda d: {**d, "frames": [{"file": "foot-0.png", "duration": 0}]}, "duration"),
(lambda d: {**d, "frames": [{"duration": 0.1}]}, "file and duration"),
(lambda d: {**d, "version": 2}, "version 1"),
(lambda d: {"kind": "something-else"}, "unsupported asset descriptor"),
(lambda d: {**d, "anchor": [1]}, "anchor"),
])
def test_invalid_descriptors_are_rejected(tmp_path, mutate, message):
source = descriptor(tmp_path)
source.write_text(json.dumps(mutate(json.loads(source.read_text()))))
with pytest.raises(ValueError, match=message):
load_asset(source)
@pytest.mark.parametrize("mutate, message", [
(lambda d: d["frame_layout"]["rows"]["walk"].append({"x": 48 * 5, "y": 0, "w": 48, "h": 40}), "outside sheet"),
(lambda d: d["frame_layout"]["rows"]["walk"].append({"x": 0, "y": 0, "w": 48.5, "h": 40}), "integer"),
(lambda d: d["frame_layout"]["rows"]["walk"].__setitem__(0, {"x": 0.5, "y": 0, "w": 48, "h": 40}), "outside sheet"),
(lambda d: d["animation"]["rows"]["walk"].update({"durations_ms": [0] * 5}), "duration_ms"),
(lambda d: d["frame_layout"].update({"rows": {}}), "no animation states"),
])
def test_invalid_atlas_manifests_are_rejected(tmp_path, mutate, message):
source = atlas(tmp_path, states=("walk",))
data = json.loads(source.read_text())
mutate(data)
source.write_text(json.dumps(data))
with pytest.raises(ValueError, match=message):
load_asset(source)
def test_frame_sequence_positional_contract_defaults_anchor_and_keeps_digests_keyword_only(tmp_path):
frame = Image.new("RGBA", (6, 4))
bare = FrameSequence((frame,), (1.0,))
assert bare.anchor == (3.0, 4.0)
assert bare.source_files == () and bare.metadata == {} and bare.source_digests == ()
assert bare.fingerprints() == {}
assert bare.identity() == {"source": None, "state": None, "fps_override": None, "frame_count": 1,
"size": [6, 4], "anchor_px": [3.0, 4.0], "durations_seconds": [1.0]}
positional = FrameSequence((frame,), (0.5,), [1, 2], (), {"source": "memory"})
assert positional.anchor == (1.0, 2.0) and positional.metadata == {"source": "memory"}
with pytest.raises(ValueError, match="SHA-256"):
FrameSequence((frame,), (1.0,), None, (tmp_path / "x.png",), {})
with pytest.raises(TypeError):
FrameSequence((frame,), (1.0,), None, (tmp_path / "x.png",), {}, ("digest",))
with pytest.raises(ValueError, match="anchor"):
FrameSequence((frame,), (1.0,), (1, float("nan")))
backed = FrameSequence((frame,), (1.0,), None, (tmp_path / "x.png",), {}, source_digests=("abc",))
assert backed.fingerprints() == {str(tmp_path / "x.png"): "abc"}
def test_playback_metadata_is_preserved_by_the_shared_adapter(tmp_path):
source = descriptor(tmp_path)
data = json.loads(source.read_text())
policy = {"loop": False, "hold_last": True, "end_frame": 4,
"events": [{"frame": 2, "name": "impact"}], "blend": "add", "direction": "SW", "body_h": 32}
data.update(policy)
source.write_text(json.dumps(data))
seq = load_asset(source)
assert {key: seq.metadata[key] for key in policy} == policy
def test_row_major_sheet_ignores_unused_cells_and_keeps_sidecar_policy(tmp_path):
sheet = Image.new("RGBA", (12, 16))
colors = ["red", "green", "blue"]
for index, color in enumerate(colors):
sheet.paste(Image.new("RGBA", (6, 8), color), ((index % 2)*6, (index // 2)*8))
sheet.save(tmp_path / "grid.png")
source = tmp_path / "grid.json"
source.write_text(json.dumps({"columns": 2, "rows": 2, "frame_width": 6, "frame_height": 8,
"frames": 3, "delay_ms": 100, "order": "row-major", "loop": False, "anchor": [2, 7]}))
seq = load_asset(source)
assert seq.anchor == (2, 7) and seq.metadata["loop"] is False
assert len(seq.frames) == 3
assert [f.getpixel((0, 0)) for f in seq.frames] == [Image.new("RGBA", (1, 1), c).getpixel((0, 0)) for c in colors]
@pytest.mark.parametrize(("module", "name", "written"), [
("sprite_gen.spec.runio", "REQUEST_KIND", "sprite-gen-request"),
("sprite_gen.video.align", "REPORT_KIND", "sprite-gen-video-cycle-align-report"),
("sprite_gen.video.frames", "REPORT_KIND", "sprite-gen-video-frames-report"),
("sprite_gen.frames.unpack_atlas", "UNPACK_SOURCE_KIND", "sprite-gen-unpack-source"),
("sprite_gen.video.prop_plate", "CANVAS_REPORT", "sprite-gen-video-canvas-report"),
])
def test_a_kind_written_to_disk_is_pinned_as_written(module, name, written):
assert getattr(importlib.import_module(module), name) == written