Skip to content

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

feat: pack game-sized atlases with playback metadata

Soohong Kim8a9506df6e8a
diff --git a/sprite_gen/_modules.py b/sprite_gen/_modules.py
index dd05e35..19cbcc7 100644
--- a/sprite_gen/_modules.py
+++ b/sprite_gen/_modules.py
@@ -46,6 +46,7 @@ MODULE_DOMAIN = {
'curation': 'curate',
'anchor': 'curate',
'compose_atlas': 'compose',
+ 'game_pack': 'compose',
'compose_cycle': 'compose',
'compose_gif': 'compose',
'compose_layers': 'compose',
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index 679eeb9..b821f29 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -11,6 +11,7 @@ from sprite_gen import _modules, gen
from sprite_gen.background import tile
from sprite_gen.curate import anchor
from sprite_gen.compose import compose_atlas, compose_cycle, compose_gif, compose_layers, export_aseprite, export_pngs
+from sprite_gen.compose import game_pack
from sprite_gen.qa import correction_loop, inspect, preview, score, motion
from sprite_gen.qa import handed as handed_check
from sprite_gen.frames import cutout, extract, slice_sheet, unpack_atlas
@@ -243,6 +244,7 @@ def _add_correction_loop(p: argparse.ArgumentParser) -> None:
COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callable[..., int]]] = {
+ "game-pack": ("Resize finished assets into game atlases with playback policies.", game_pack.add_arguments, game_pack.run),
"background-tile": ("Quilt a repeating RGBA background and measure its join.", tile.add_arguments, tile.run),
"shadow": ("Project silhouette shadows from any supported asset.", shadow.add_arguments, shadow.run),
"inspect-motion": ("Measure asset timing and contact evidence without changing animation.", motion.add_arguments, motion.run),
diff --git a/sprite_gen/compose/game_pack.py b/sprite_gen/compose/game_pack.py
new file mode 100644
index 0000000..58273ad
--- /dev/null
+++ b/sprite_gen/compose/game_pack.py
@@ -0,0 +1,246 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Resize finished assets and publish an immutable game atlas pack."""
+from __future__ import annotations
+
+import argparse
+from io import BytesIO
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import tempfile
+
+from PIL import Image
+
+from sprite_gen.spec.assets import finite, load_asset_states
+
+MAX_PAGE_SIZE = 4096
+MAX_BYTES = 50_000_000
+
+
+def _integer(value, name, *, maximum=None):
+ number = finite(value, name, positive=True)
+ if number != int(number) or maximum is not None and number > maximum:
+ raise ValueError(f"{name} must be an integer between 1 and {maximum or 'its limit'}")
+ return int(number)
+
+
+def _name(value):
+ if not isinstance(value, str) or not re.fullmatch(r"[A-Za-z0-9_.-]+", value):
+ raise ValueError("asset id and state must use letters, digits, underscore, dot or dash")
+ return value
+
+
+def _policy(sequence, entry):
+ count = len(sequence.frames)
+ metadata = sequence.metadata
+ result = {}
+ for key, default in (("loop", True), ("hold_last", False), ("end_frame", count - 1),
+ ("blend", "normal"), ("events", []), ("direction", None)):
+ result[key] = entry.get(key, metadata.get(key, default))
+ for key in ("loop", "hold_last"):
+ if type(result[key]) is not bool:
+ raise ValueError(f"{key} must be a bool")
+ if result["blend"] not in ("normal", "add"):
+ raise ValueError("blend must be normal or add")
+ if type(result["end_frame"]) is not int or not 0 <= result["end_frame"] < count:
+ raise ValueError("end_frame must index a playback frame (zero-based)")
+ if result["direction"] is not None and not isinstance(result["direction"], str):
+ raise ValueError("direction must be a string or null")
+ if not isinstance(result["events"], list):
+ raise ValueError("events must be a list")
+ for event in result["events"]:
+ if (not isinstance(event, dict) or type(event.get("frame")) is not int
+ or not 0 <= event["frame"] < count or not isinstance(event.get("name"), str) or not event["name"]):
+ raise ValueError("each event needs a zero-based playback frame and a name")
+ result["durations_ms"] = [duration * 1000 for duration in sequence.durations]
+ return result
+
+
+def _display(sequence, entry):
+ display = entry.get("display")
+ if not isinstance(display, dict) or len(display) != 1 or not set(display) <= {"width", "height", "body_height"}:
+ raise ValueError("display requires exactly one of width, height or body_height")
+ dimension, value = next(iter(display.items()))
+ target = _integer(value, f"display {dimension}")
+ width, height = sequence.size
+ if dimension == "body_height":
+ reference = finite(entry.get("source_body_height", sequence.metadata.get("body_h")),
+ "source_body_height (required when the asset has no body_h)", positive=True)
+ else:
+ reference = width if dimension == "width" else height
+ scale = target / reference
+ size = (max(1, round(width * scale)), max(1, round(height * scale)))
+ anchor = [sequence.anchor[0] * size[0] / width, sequence.anchor[1] * size[1] / height]
+ sampling = entry.get("resample", "nearest" if sequence.metadata.get("frame_variant") == "pixel" else "lanczos")
+ if sampling not in ("nearest", "lanczos"):
+ raise ValueError("resample must be nearest or lanczos")
+ return size, anchor, Image.Resampling.NEAREST if sampling == "nearest" else Image.Resampling.LANCZOS
+
+
+def _prepare(request, base, page_size):
+ if not isinstance(request, dict) or request.get("version") != 1:
+ raise ValueError("game pack request requires version 1")
+ entries = request.get("assets")
+ if not isinstance(entries, list) or not entries:
+ raise ValueError("assets must be a nonempty list")
+ ids, animations, frames, sources = set(), {}, [], set()
+ for entry in entries:
+ if not isinstance(entry, dict):
+ raise ValueError("each asset must be an object")
+ asset_id = _name(entry.get("id"))
+ if asset_id in ids:
+ raise ValueError(f"duplicate asset id: {asset_id}")
+ ids.add(asset_id)
+ if not isinstance(entry.get("source"), str) or not entry["source"]:
+ raise ValueError("each asset requires a source path")
+ sequences = load_asset_states(base / entry["source"], state=entry.get("state"), fps=entry.get("fps"), anchor=entry.get("anchor"))
+ for state, sequence in sequences.items():
+ key = asset_id if state is None else f"{asset_id}/{_name(state)}"
+ size, anchor, sampling = _display(sequence, entry)
+ # One extruded pixel on each edge keeps filtered textures from bleeding.
+ if max(size) + 2 > page_size:
+ raise ValueError(f"{key}: frame {size} plus padding exceeds page size {page_size}")
+ animation = _policy(sequence, entry)
+ animation.update(anchor=anchor, size={"w": size[0], "h": size[1]}, frames=[])
+ for index, image in enumerate(sequence.frames):
+ name = f"{key}/{index:06d}"
+ animation["frames"].append(name)
+ frames.append((name, image.resize(size, sampling), anchor))
+ animations[key] = animation
+ sources.update(sequence.source_files)
+ return dict(sorted(animations.items())), sorted(frames, key=lambda f: f[0]), sources
+
+
+def _layout(frames, limit):
+ """Deterministic shelf placement; playback order is independent of texture position."""
+ pages, placed = [], []
+ x = y = row_height = width = height = 0
+ for name, image, anchor in frames:
+ w, h = image.width + 2, image.height + 2
+ if x + w > limit:
+ x, y, row_height = 0, y + row_height, 0
+ if y + h > limit:
+ pages.append((width, height, placed))
+ placed = []
+ x = y = row_height = width = height = 0
+ placed.append((name, image, anchor, x + 1, y + 1))
+ x += w
+ row_height = max(row_height, h)
+ width, height = max(width, x), max(height, y + h)
+ pages.append((width, height, placed))
+ return pages
+
+
+def _paste_extruded(sheet, image, x, y):
+ w, h = image.size
+ sheet.paste(image, (x, y))
+ sheet.paste(image.crop((0, 0, w, 1)), (x, y - 1))
+ sheet.paste(image.crop((0, h - 1, w, h)), (x, y + h))
+ sheet.paste(image.crop((0, 0, 1, h)), (x - 1, y))
+ sheet.paste(image.crop((w - 1, 0, w, h)), (x + w, y))
+ for dx, sx in ((-1, 0), (w, w - 1)):
+ for dy, sy in ((-1, 0), (h, h - 1)):
+ sheet.putpixel((x + dx, y + dy), image.getpixel((sx, sy)))
+
+
+def _encode(pages, animations, max_bytes):
+ payloads, textures = {}, []
+ total = 0
+ for index, (width, height, placed) in enumerate(pages):
+ sheet = Image.new("RGBA", (width, height))
+ records = {}
+ for name, image, anchor, x, y in placed:
+ _paste_extruded(sheet, image, x, y)
+ size = {"w": image.width, "h": image.height}
+ records[name] = {"frame": {"x": x, "y": y, **size}, "rotated": False, "trimmed": False,
+ "spriteSourceSize": {"x": 0, "y": 0, **size}, "sourceSize": size,
+ "pivot": {"x": anchor[0]/image.width, "y": anchor[1]/image.height}}
+ png_name, webp_name = f"atlas-{index:03d}.png", f"atlas-{index:03d}.webp"
+ for name, fmt, options in ((png_name, "PNG", {"compress_level": 9}),
+ (webp_name, "WEBP", {"lossless": True, "exact": True, "method": 6})):
+ buffer = BytesIO()
+ sheet.save(buffer, format=fmt, **options)
+ payloads[name] = buffer.getvalue()
+ total += len(payloads[name])
+ if total > max_bytes:
+ raise ValueError(f"game pack exceeds {max_bytes} bytes (50 MB maximum)")
+ textures.append({"image": png_name, "webp": webp_name, "frames": records,
+ "meta": {"image": png_name, "format": "RGBA8888", "size": {"w": width, "h": height}, "scale": "1"}})
+ result = {"kind": "sprite-gen-game-pack", "version": 1, "textures": textures, "animations": animations}
+ payloads["game-pack.json"] = (json.dumps(result, ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n").encode()
+ if total + len(payloads["game-pack.json"]) > max_bytes:
+ raise ValueError(f"game pack exceeds {max_bytes} bytes (50 MB maximum, including its manifest)")
+ return result, payloads
+
+
+def _publish(out_dir, payloads):
+ """One atomic directory rename; concurrent publishers cannot interleave packs."""
+ def identical():
+ return (out_dir.is_dir() and {p.name for p in out_dir.iterdir()} == set(payloads)
+ and all((out_dir / name).is_file() and (out_dir / name).read_bytes() == data
+ for name, data in payloads.items()))
+
+ if out_dir.exists():
+ if identical():
+ return
+ raise ValueError("output directory already exists with different content; use a new directory")
+ out_dir.parent.mkdir(parents=True, exist_ok=True)
+ stage = Path(tempfile.mkdtemp(prefix=f".{out_dir.name}-", dir=out_dir.parent))
+ try:
+ for name, data in payloads.items():
+ with (stage / name).open("wb") as handle:
+ handle.write(data)
+ handle.flush()
+ os.fsync(handle.fileno())
+ try:
+ stage.rename(out_dir)
+ except OSError:
+ if not identical():
+ raise
+ finally:
+ if stage.exists():
+ shutil.rmtree(stage)
+
+
+def pack(request: Path, out_dir: Path, *, page_size=MAX_PAGE_SIZE, max_bytes=MAX_BYTES):
+ page_size = _integer(page_size, "page size", maximum=MAX_PAGE_SIZE)
+ max_bytes = _integer(max_bytes, "max bytes", maximum=MAX_BYTES)
+ request, out_dir = Path(request).expanduser().resolve(), Path(out_dir).expanduser().resolve()
+ document = json.loads(request.read_text(encoding="utf-8"))
+ animations, frames, sources = _prepare(document, request.parent, page_size)
+ if any(path == out_dir or out_dir in path.parents for path in sources | {request}):
+ raise ValueError("output directory must not contain any source file")
+ result, payloads = _encode(_layout(frames, page_size), animations, max_bytes)
+ _publish(out_dir, payloads)
+ return result
+
+
+def add_arguments(parser):
+ parser.epilog = "events[].frame and end_frame are zero-based indices in output playback order."
+ parser.add_argument("--request", type=Path, required=True, help="JSON result list with display sizes")
+ parser.add_argument("--out-dir", type=Path, required=True, help="new directory for the immutable pack")
+ parser.add_argument("--page-size", type=int, default=MAX_PAGE_SIZE)
+ parser.add_argument("--max-bytes", type=int, default=MAX_BYTES)
+
+
+def run(**kwargs):
+ try:
+ result = pack(kwargs["request"], kwargs["out_dir"], page_size=kwargs.get("page_size", MAX_PAGE_SIZE),
+ max_bytes=kwargs.get("max_bytes", MAX_BYTES))
+ except (ValueError, OSError) as exc:
+ raise SystemExit(f"game-pack: {exc}") from exc
+ print(json.dumps({"ok": True, "manifest": str(Path(kwargs["out_dir"]) / "game-pack.json"),
+ "pages": len(result["textures"]), "animations": len(result["animations"])}))
+ return 0
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ add_arguments(parser)
+ return run(**vars(parser.parse_args()))
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/sprite_gen/spec/assets.py b/sprite_gen/spec/assets.py
index cc3c116..e7ad28e 100644
--- a/sprite_gen/spec/assets.py
+++ b/sprite_gen/spec/assets.py
@@ -177,6 +177,7 @@ class _Snapshot:
def __init__(self):
self.digests: dict[Path, str] = {}
self._bytes: dict[Path, bytes] = {}
+ self._images: dict[Path, Image.Image] = {}
def read(self, path: Path) -> bytes:
if path not in self._bytes:
@@ -186,7 +187,9 @@ class _Snapshot:
return self._bytes[path]
def image(self, path: Path) -> Image.Image:
- return _decode_image(self.read(path))
+ if path not in self._images:
+ self._images[path] = _decode_image(self.read(path))
+ return self._images[path]
def json(self, path: Path):
return json.loads(self.read(path).decode("utf-8"))
@@ -212,8 +215,49 @@ def _integer(value, name):
def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSequence:
+ source = Path(source).expanduser().resolve()
+ return _load_asset(source, _Snapshot(), state=state, fps=fps, anchor=anchor)
+
+
+def load_asset_states(source: Path, *, state=None, fps=None, anchor=None) -> dict[str | None, FrameSequence]:
+ """Read every declared state from one snapshot; never discover frames by filename sort."""
source = Path(source).expanduser().resolve()
snapshot = _Snapshot()
+ states = [state]
+ if state is None and source.suffix.lower() == ".json":
+ data = snapshot.json(source)
+ if not isinstance(data, dict):
+ raise ValueError("asset descriptor must be an object")
+ if "frame_layout" in data:
+ states = list(data["frame_layout"]["rows"])
+ elif data.get("kind") == "sprite-gen-video-set-sheet":
+ states = [row["code"] for row in data["rows"]]
+ elif isinstance(data.get("rows"), list) and "cell" in data:
+ states = data["rows"]
+ if not states or len(set(states)) != len(states):
+ raise ValueError("asset states must be nonempty and unique")
+ return {key: _load_asset(source, snapshot, state=key, fps=fps, anchor=anchor) for key in states}
+
+
+PLAYBACK_FIELDS = ("loop", "hold_last", "end_frame", "events", "blend", "direction", "body_h", "frame_variant")
+
+
+def _grid_frames(sheet, columns, rows, width, height, count, *, row=None):
+ columns, rows, width, height, count = (
+ _integer(v, name) for v, name in zip((columns, rows, width, height, count),
+ ("columns", "rows", "width", "height", "frames")))
+ if sheet.size != (columns * width, rows * height):
+ raise ValueError("sheet size disagrees with its sidecar")
+ if row is not None and (type(row) is not int or not 0 <= row < rows):
+ raise ValueError("sheet row is outside the sheet")
+ if count > (columns if row is not None else columns * rows):
+ raise ValueError("sheet frame count exceeds its cells")
+ return [sheet.crop(((i % columns) * width, (row if row is not None else i // columns) * height,
+ (i % columns + 1) * width, ((row if row is not None else i // columns) + 1) * height))
+ for i in range(count)]
+
+
+def _load_asset(source, snapshot, *, state=None, fps=None, anchor=None):
meta = {"source": str(source)}
declared_anchor = None
if source.suffix.lower() != ".json":
@@ -225,6 +269,7 @@ def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSeque
data = snapshot.json(source)
if not isinstance(data, dict):
raise ValueError("asset descriptor must be an object")
+ meta.update({key: data[key] for key in PLAYBACK_FIELDS if key in data})
declared_anchor = data.get("anchor")
if data.get("kind") == "sprite-gen-asset":
if data.get("version") != 1 or state is not None:
@@ -250,11 +295,45 @@ def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSeque
raise ValueError("atlas frame rectangle outside sheet")
frames.append(sheet.crop((int(x), int(y), int(x)+w, int(y)+h)))
anim = data["animation"]["rows"][state]
+ meta.update({key: anim[key] for key in PLAYBACK_FIELDS if key in anim})
+ declared_anchor = anim.get("anchor", declared_anchor)
if "durations_ms" in anim:
durations = [finite(v, "duration_ms", positive=True) / 1000 for v in anim["durations_ms"]]
else:
durations = [1 / finite(anim.get("fps"), "atlas fps", positive=True)] * len(frames)
- meta.update(state=state, loop=bool(anim.get("loop", True)))
+ meta.update(state=state, loop=anim.get("loop", True))
+ elif data.get("kind") == "sprite-gen-video-set-sheet":
+ if data.get("schema") != 1:
+ raise ValueError("direction sheet requires schema 1")
+ rows = data["rows"]
+ by_code = {row["code"]: row for row in rows}
+ if len(by_code) != len(rows) or len({row["row"] for row in rows}) != len(rows):
+ raise ValueError("direction sheet rows must be unique")
+ state = _choose(by_code, state)
+ selected = by_code[state]
+ sheet = snapshot.image((source.parent / data["sheet"]).resolve())
+ frames = _grid_frames(sheet, data["columns"], len(rows), data["cell_w"], data["cell_h"],
+ selected["frames"], row=selected["row"])
+ durations = [finite(selected["delay_ms"], "delay_ms", positive=True)/1000] * len(frames)
+ meta.update({key: selected[key] for key in PLAYBACK_FIELDS if key in selected})
+ meta.update(state=state, direction=state)
+ declared_anchor = selected.get("anchor", declared_anchor)
+ elif isinstance(data.get("rows"), list) and "cell" in data:
+ # Row-labelled direction sheets: explicit row order, never compass sorting.
+ rows = data["rows"]
+ if len(set(rows)) != len(rows):
+ raise ValueError("direction sheet rows must be unique")
+ state = _choose(dict.fromkeys(rows, True), state)
+ sheet = snapshot.image(source.with_suffix(".png"))
+ frames = _grid_frames(sheet, data["frames"], len(rows), *data["cell"], data["frames"], row=rows.index(state))
+ durations = [1/finite(data["fps"], "fps", positive=True)] * len(frames)
+ meta.update(state=state, direction=state)
+ elif all(k in data for k in ("columns", "rows", "frame_width", "frame_height", "frames", "delay_ms")):
+ if state is not None or data.get("order") != "row-major":
+ raise ValueError("grid sheet requires row-major order and no --state")
+ sheet = snapshot.image(source.with_suffix(".png"))
+ frames = _grid_frames(sheet, data["columns"], data["rows"], data["frame_width"], data["frame_height"], data["frames"])
+ durations = [finite(data["delay_ms"], "delay_ms", positive=True)/1000] * len(frames)
elif all(k in data for k in ("frames", "w", "h", "delay_ms")):
if state is not None:
raise ValueError("--state is only valid for atlas input")
@@ -266,7 +345,7 @@ def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSeque
durations = [finite(data["delay_ms"], "delay_ms", positive=True)/1000] * n
# `video-loop` writes `loop: false` for a one-shot cut (rest -> action -> rest);
# an older sidecar without the key is a loop, as every strip was before.
- meta["loop"] = bool(data.get("loop", True))
+ meta["loop"] = data.get("loop", True)
else:
raise ValueError("unsupported asset descriptor; use sprite-gen-asset, loop strip sidecar or atlas manifest")
if not frames:
diff --git a/tests/spec/test_assets.py b/tests/spec/test_assets.py
index 2b4dc2b..bd34228 100644
--- a/tests/spec/test_assets.py
+++ b/tests/spec/test_assets.py
@@ -316,3 +316,47 @@ def test_frame_sequence_positional_contract_defaults_anchor_and_keeps_digests_ke
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]
+
+
+def test_all_direction_rows_share_one_snapshot_decode(tmp_path, monkeypatch):
+ source = tmp_path / "directions.json"
+ source.write_text(json.dumps({"cell": [6, 8], "frames": 2, "fps": 10, "rows": ["NE", "SW"]}))
+ image = Image.new("RGBA", (12, 16), "red")
+ image.paste(Image.new("RGBA", (12, 8), "blue"), (0, 8))
+ image.save(tmp_path / "directions.png")
+ reads, decodes = [], []
+ read, decode = assets._read_bytes, assets._decode_image
+ monkeypatch.setattr(assets, "_read_bytes", lambda p: (reads.append(p.name), read(p))[1])
+ monkeypatch.setattr(assets, "_decode_image", lambda data: (decodes.append(len(data)), decode(data))[1])
+ sequences = assets.load_asset_states(source)
+ assert list(sequences) == ["NE", "SW"]
+ assert reads == ["directions.json", "directions.png"] and len(decodes) == 1
+ assert sequences["NE"].frames[0].getpixel((0, 0)) == (255, 0, 0, 255)
+ assert sequences["SW"].frames[0].getpixel((0, 0)) == (0, 0, 255, 255)
+ assert sequences["NE"].fingerprints() == sequences["SW"].fingerprints()