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.pyindex 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.pyindex 679eeb9..b821f29 100644--- a/sprite_gen/cli.py+++ b/sprite_gen/cli.py@@ -11,6 +11,7 @@ from sprite_gen import _modules, genfrom sprite_gen.background import tilefrom sprite_gen.curate import anchorfrom sprite_gen.compose import compose_atlas, compose_cycle, compose_gif, compose_layers, export_aseprite, export_pngs+from sprite_gen.compose import game_packfrom sprite_gen.qa import correction_loop, inspect, preview, score, motionfrom sprite_gen.qa import handed as handed_checkfrom 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.pynew file mode 100644index 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.pyindex 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 = Noneif source.suffix.lower() != ".json":@@ -225,6 +269,7 @@ def load_asset(source: Path, *, state=None, fps=None, anchor=None) -> FrameSequedata = 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) -> FrameSequeraise 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) -> FrameSequedurations = [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.pyindex 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_keFrameSequence((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()