Skip to content

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

test: define game pack export contract

Soohong Kimaba92a23cf35
diff --git a/tests/compose/test_game_pack.py b/tests/compose/test_game_pack.py
new file mode 100644
index 0000000..0d3471b
--- /dev/null
+++ b/tests/compose/test_game_pack.py
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Game-sized exports retain playback order, pivots and policies across pages."""
+import json
+import subprocess
+import sys
+
+import pytest
+from PIL import Image
+
+from sprite_gen.compose import game_pack
+
+
+def write_json(path, data):
+ path.write_text(json.dumps(data), encoding="utf-8")
+ return path
+
+
+def strip(tmp_path):
+ image = Image.new("RGBA", (36, 20))
+ for index, color in enumerate(("red", "green", "blue")):
+ image.paste(Image.new("RGBA", (12, 20), color), (index * 12, 0))
+ image.save(tmp_path / "walk.strip.png")
+ return write_json(tmp_path / "walk.strip.json", {
+ "frames": 3, "w": 12, "h": 20, "delay_ms": 80,
+ "body_h": 16, "anchor": [4, 18], "loop": False, "hold_last": True,
+ "end_frame": 2, "events": [{"frame": 1, "name": "impact"}], "blend": "add",
+ "direction": "NE",
+ })
+
+
+def request(tmp_path, entries):
+ return write_json(tmp_path / "game.json", {"version": 1, "assets": entries})
+
+
+def pixels(out, result, animation):
+ frames = {key: (page, value) for page in result["textures"] for key, value in page["frames"].items()}
+ found = []
+ for key in result["animations"][animation]["frames"]:
+ page, record = frames[key]
+ rect = record["frame"]
+ with Image.open(out / page["image"]) as im:
+ found.append(im.crop((rect["x"], rect["y"], rect["x"]+rect["w"], rect["y"]+rect["h"])))
+ return found
+
+
+def test_mixed_export_preserves_timing_order_policy_pivot_and_pixel_colors(tmp_path):
+ strip(tmp_path)
+ Image.new("RGBA", (4, 6), (61, 29, 243, 127)).save(tmp_path / "pixel.png")
+ Image.new("RGBA", (12, 12), "yellow").save(tmp_path / "painting.png")
+ source = request(tmp_path, [
+ {"id": "walk", "source": "walk.strip.json", "display": {"body_height": 8}},
+ {"id": "pixel", "source": "pixel.png", "display": {"height": 3}, "resample": "nearest"},
+ {"id": "painting", "source": "painting.png", "display": {"width": 6}},
+ ])
+ out = tmp_path / "out"
+ result = game_pack.pack(source, out)
+ assert json.loads((out / "game-pack.json").read_text()) == result
+ anim = result["animations"]["walk"]
+ assert (anim["loop"], anim["hold_last"], anim["end_frame"], anim["blend"], anim["direction"]) == (False, True, 2, "add", "NE")
+ assert anim["events"] == [{"frame": 1, "name": "impact"}]
+ assert anim["durations_ms"] == [80, 80, 80]
+ assert anim["anchor"] == [2, 9]
+ assert [f.getpixel((1, 1)) for f in pixels(out, result, "walk")] == [(255, 0, 0, 255), (0, 128, 0, 255), (0, 0, 255, 255)]
+ assert {f.size for f in pixels(out, result, "walk")} == {(6, 10)}
+ assert pixels(out, result, "pixel")[0].getpixel((0, 0)) == (61, 29, 243, 127)
+ # The hash fields consumed by Phaser 4.2.1 JSONHash, including normalized pivot.
+ for page in result["textures"]:
+ assert isinstance(page["frames"], dict)
+ with Image.open(out / page["image"]) as png, Image.open(out / page["webp"]) as webp:
+ assert png.size == webp.size
+ assert png.convert("RGBA").tobytes() == webp.convert("RGBA").tobytes()
+ assert max(png.size) <= 4096
+ for value in page["frames"].values():
+ box, size = value["frame"], value["sourceSize"]
+ assert value["rotated"] is False and value["trimmed"] is False
+ assert value["spriteSourceSize"] == {"x": 0, "y": 0, **size}
+ assert 0 <= box["x"] <= png.width - box["w"]
+ assert 0 <= box["y"] <= png.height - box["h"]
+ frame = next(v for p in result["textures"] for k, v in p["frames"].items() if k == anim["frames"][0])
+ assert frame["pivot"] == {"x": 1/3, "y": 0.9}
+
+
+def test_direction_sheet_uses_declared_row_positions_and_lengths(tmp_path):
+ sheet = Image.new("RGBA", (18, 16))
+ colors = {"N": ["red", "green", "blue"], "S": ["yellow", "purple"]}
+ for row, code in enumerate(("S", "N")):
+ for col, color in enumerate(colors[code]):
+ sheet.paste(Image.new("RGBA", (6, 8), color), (col * 6, row * 8))
+ sheet.save(tmp_path / "set.png")
+ write_json(tmp_path / "set.json", {
+ "kind": "sprite-gen-video-set-sheet", "schema": 1, "sheet": "set.png",
+ "columns": 3, "cell_w": 6, "cell_h": 8, "anchor": [2, 7], "order": ["N", "S"],
+ "rows": [{"code": "N", "row": 1, "frames": 3, "delay_ms": 75, "body_h": 6},
+ {"code": "S", "row": 0, "frames": 2, "delay_ms": 120, "body_h": 6}],
+ })
+ source = request(tmp_path, [{"id": "walk", "source": "set.json", "display": {"body_height": 3}}])
+ out = tmp_path / "out"
+ result = game_pack.pack(source, out)
+ assert list(result["animations"]) == ["walk/N", "walk/S"]
+ for code in ("N", "S"):
+ anim = result["animations"][f"walk/{code}"]
+ assert anim["direction"] == code
+ assert anim["loop"] is True and anim["hold_last"] is False
+ assert anim["anchor"] == [1, 3.5]
+ expected = [Image.new("RGBA", (1, 1), c).getpixel((0, 0)) for c in colors[code]]
+ assert [f.getpixel((1, 1)) for f in pixels(out, result, f"walk/{code}")] == expected
+
+
+def test_runtime_atlas_repeated_rectangles_and_variable_durations(tmp_path):
+ strip(tmp_path)
+ rects = [{"x": i * 12, "y": 0, "w": 12, "h": 20} for i in (2, 0, 2, 1)]
+ write_json(tmp_path / "atlas.json", {
+ "sprite_sheet_alpha": "walk.strip.png", "frame_layout": {"rows": {"hit": rects}},
+ "animation": {"rows": {"hit": {"durations_ms": [40, 160, 90, 100], "loop": False,
+ "hold_last": True, "anchor": [5, 19], "events": [{"frame": 2, "name": "hit"}], "end_frame": 3}}},
+ })
+ src = request(tmp_path, [{"id": "actor", "source": "atlas.json", "display": {"height": 10}, "resample": "nearest"}])
+ result = game_pack.pack(src, tmp_path / "out")
+ anim = result["animations"]["actor/hit"]
+ assert anim["durations_ms"] == [40, 160, 90, 100]
+ assert anim["anchor"] == [2.5, 9.5]
+ assert anim["events"][0]["frame"] == 2
+ assert [im.getpixel((0, 0)) for im in pixels(tmp_path / "out", result, "actor/hit")] == [(0, 0, 255, 255), (255, 0, 0, 255), (0, 0, 255, 255), (0, 128, 0, 255)]
+
+
+def test_multipage_and_repeated_export_are_byte_identical(tmp_path):
+ strip(tmp_path)
+ src = request(tmp_path, [{"id": "walk", "source": "walk.strip.json", "display": {"height": 10}}])
+ result = game_pack.pack(src, tmp_path / "first", page_size=12)
+ assert len(result["textures"]) == 3
+ game_pack.pack(src, tmp_path / "second", page_size=12)
+ before = {p.name: p.read_bytes() for p in (tmp_path / "first").iterdir()}
+ assert before == {p.name: p.read_bytes() for p in (tmp_path / "second").iterdir()}
+ game_pack.pack(src, tmp_path / "first", page_size=12)
+ assert before == {p.name: p.read_bytes() for p in (tmp_path / "first").iterdir()}
+ # Changing a published pack is explicit: a fresh output directory is required.
+ with pytest.raises(ValueError, match="different|existing|exists"):
+ game_pack.pack(src, tmp_path / "first", page_size=24)
+ assert before == {p.name: p.read_bytes() for p in (tmp_path / "first").iterdir()}
+
+
[email protected]("change,match", [
+ ({"display": {"height": 0}}, "positive"),
+ ({"display": {"height": 5000}}, "4096|page"),
+ ({"events": [{"frame": 3, "name": "bad"}]}, "event"),
+ ({"loop": "false"}, "bool"),
+ ({"end_frame": -1}, "end_frame"),
+ ({"resample": "typo"}, "resample"),
+])
+def test_bad_input_never_publishes_partial_output(tmp_path, change, match):
+ strip(tmp_path)
+ entry = {"id": "walk", "source": "walk.strip.json", "display": {"height": 10}, **change}
+ src = request(tmp_path, [entry])
+ with pytest.raises(ValueError, match=match):
+ game_pack.pack(src, tmp_path / "out")
+ assert not (tmp_path / "out").exists()
+
+
+def test_size_limit_counts_both_images_and_manifest_before_publish(tmp_path):
+ strip(tmp_path)
+ src = request(tmp_path, [{"id": "walk", "source": "walk.strip.json", "display": {"height": 10}}])
+ with pytest.raises(ValueError, match="byte|MB"):
+ game_pack.pack(src, tmp_path / "out", max_bytes=10)
+ assert not (tmp_path / "out").exists()
+ for kwargs in ({"page_size": 4097}, {"max_bytes": 50_000_001}):
+ with pytest.raises(ValueError):
+ game_pack.pack(src, tmp_path / "out", **kwargs)
+
+
+def test_cli_dispatch_and_real_files(tmp_path):
+ strip(tmp_path)
+ src = request(tmp_path, [{"id": "walk", "source": "walk.strip.json", "display": {"height": 10}}])
+ call = subprocess.run([sys.executable, "-m", "sprite_gen.cli", "game-pack", "--request", str(src),
+ "--out-dir", str(tmp_path / "out")], capture_output=True, text=True)
+ assert call.returncode == 0, call.stderr
+ assert json.loads(call.stdout)["ok"] is True
+ assert (tmp_path / "out" / "game-pack.json").is_file()