Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(game-pack): sound no longer overwrites the version 2 tile files
Soohong Kim33f058170bc0
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 0f5ce94..3c7f180 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,7 +8,7 @@ All notable public changes to `sprite-gen` are recorded here. Versions track the- **New: alpha haze cleanup for transparent sheets (`frames.alpha_floor.clear_haze`).** Pixels at or above a floor, and faint pixels within a few pixels of them (an object's anti-aliased edge), are kept byte for byte; every other faint pixel becomes fully transparent. The report measures the haze share before and after and counts the solid and edge pixels that changed (`0`). Used by `ui-kit` (on by default) and `slice-sheet --alpha-floor N` (off by default; writes `<prefix>alpha-cleanup.json`). `slice-sheet --chroma-key none` cuts a sheet that is already transparent on its own alpha ([sheet-slicing](docs/sheet-slicing.md#transparent-sheets)).- **New verb: `ui-kit` splits a game UI kit sheet into nine-slice elements.** `gen --layout-guide ui-kit` attaches a fixed square layout (panel, button, pressed button, card frame, HP and XP bar frames, timer badge) and asks for each element in its box. `ui-kit --sheet uikit.png --out-dir ui/` clears the haze, assigns parts to boxes by centroid, and writes each element's PNG and `ui-kit.json`: its rectangle, its stretch (`xy`, `x` for the bars, `none` for the badge), nine-slice insets measured so that every corner ornament and end cap lies in a fixed slice, and the content padding (a bar frame's track, a panel's text area). An ornament in the middle of an edge, an empty box or a stray part is reported or refused ([ui-kit](docs/ui-kit.md)). `--layout-guide` alone is still the one-slot figure guide.- **New: `game-pack` request and manifest version 2 with `images`, `tiles` and `ui`.** Single images (props) are atlas frames with an anchor and an optional footprint (`"base"` measures where the image meets the ground); tiles are their own PNG and WebP files with their stored and on-screen sizes; `ui.kit` reads a `ui-kit` report into nine-slice entries (frame, size, stretch, insets, padding) and `ui.icons` adds fixed icons. Every number is in pixels of the stored image. A version 1 request is packed byte for byte as before, and a version 1 request naming the new sections is refused ([game-pack](docs/game-pack.md#version-2-images-tiles-and-ui)).-- **Tests** — `tests/background/test_tile_xy.py` (an exact doubly periodic crop, a join that stays visible on one axis names that axis, the cyclic seam), `tests/frames/test_alpha_floor.py` (a haze ring cleared, thin strokes and their anti-aliased edges kept), `tests/frames/test_ui_kit.py` (a synthetic sheet on the layout: insets to the pixel over corner ornaments, a long flourish, a bar's end gem and cap; badge padding inside its ring; a packed kit at four scales keeps ornament fringes out of the stretched middle), `tests/frames/test_slice_sheet_transparent.py`, `tests/compose/test_game_pack_v2.py` (the manifest field by field, refusals, and a version 1 manifest and page pixels frozen from 2.44.0) and the `--layout-guide ui-kit` cases in `tests/gen/test_layout_guide.py`.+- **Tests** — `tests/background/test_tile_xy.py` (an exact doubly periodic crop, a join that stays visible on one axis names that axis, the cyclic seam), `tests/frames/test_alpha_floor.py` (a haze ring cleared, thin strokes and their anti-aliased edges kept), `tests/frames/test_ui_kit.py` (a synthetic sheet on the layout: insets to the pixel over corner ornaments, a long flourish, a bar's end gem and cap; badge padding inside its ring; a packed kit at four scales keeps ornament fringes out of the stretched middle), `tests/frames/test_slice_sheet_transparent.py`, `tests/compose/test_game_pack_v2.py` (the manifest field by field, refusals, and a version 1 manifest and page pixels frozen from 2.44.0), `tests/compose/test_game_pack_audio.py` (a version 1 pack with sound keeps its file list, manifest bytes and page pixels from 2.44.0; a version 2 pack with sound adds only its tile files) and the `--layout-guide ui-kit` cases in `tests/gen/test_layout_guide.py`.- Bump audio processing recipe to version 3, require `ffprobe` on `PATH`, export M4A with `-movie_timescale 48000`, and validate AAC stream duration with `ffprobe`.- Add bounded one-frame decoded length tolerance, preserving loop duration, trimming one-shots, and rejecting shorter buffers and undersized overlaps at export.diff --git a/sprite_gen/compose/game_pack.py b/sprite_gen/compose/game_pack.pyindex 5921059..5e3f889 100644--- a/sprite_gen/compose/game_pack.py+++ b/sprite_gen/compose/game_pack.py@@ -441,15 +441,16 @@ def pack(request: Path, out_dir: Path, *, page_size=MAX_PAGE_SIZE, max_bytes=MAXdocument = json.loads(request.read_text(encoding="utf-8"))version = _version(document)animations, frames, sources = _prepare(document, request.parent, page_size, version)- sections = files = None+ # `files` is the audio loop's name below; the version 2 tile files must not share it.+ sections = tile_files = Noneif version == 2:- sections, scene_frames, files, scene_sources = _prepare_scene(document, request.parent, page_size)+ sections, scene_frames, tile_files, scene_sources = _prepare_scene(document, request.parent, page_size)frames = sorted(frames + scene_frames, key=lambda f: f[0])sources |= scene_sourcesnames = [name for name, _image, _anchor in frames]if len(set(names)) != len(names):raise ValueError("two atlas frames share a name; rename an asset or scene entry")- if not frames and not files:+ if not frames and not tile_files:raise ValueError("game pack request declares nothing to pack")audio_entries = document.get("audio", [])if not isinstance(audio_entries, list):@@ -473,7 +474,7 @@ def pack(request: Path, out_dir: Path, *, page_size=MAX_PAGE_SIZE, max_bytes=MAXsources.update(paths)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) if frames else [], animations, max_bytes, sections, files)+ result, payloads = _encode(_layout(frames, page_size) if frames else [], animations, max_bytes, sections, tile_files)if audio:helper, module = audio_player()audio_payloads[helper["path"]] = modulediff --git a/tests/compose/test_game_pack_audio.py b/tests/compose/test_game_pack_audio.pyindex dd54fc5..7aabd51 100644--- a/tests/compose/test_game_pack_audio.py+++ b/tests/compose/test_game_pack_audio.py@@ -73,3 +73,50 @@ def test_broken_audio_cannot_publish_a_partial_pack(tmp_path, defect):(tmp_path/'audio'/'sound.json').write_text(json.dumps(manifest))with pytest.raises(ValueError): pack(path, tmp_path/'bad')assert not (tmp_path/'bad').exists()+++# A version 1 pack with sound, packed by 2.44.0 (before request version 2): its file names, the+# manifest's exact bytes and the page's decoded pixels (encoded PNG/WebP bytes depend on the zlib and+# libwebp build). The sound files and the helper are compared byte for byte below.+V1_AUDIO_FILES = ['atlas-000.png', 'atlas-000.webp', 'audio-hit.m4a', 'audio-hit.ogg', 'game-pack.json',+ 'sprite-gen-audio-v2.mjs']+V1_AUDIO_MANIFEST_SHA256 = 'b79d31a4f38982f2c4a97b2aa5ddb4e77b545acee29210dac6a0e6649f9f5b67'+V1_AUDIO_PAGE_PIXELS_SHA256 = '834f7685ed723160d26784bb8ba1153e5f8ae56f5ddc8f51ebb0c54b1a63e067'+++def with_sound(tmp_path):+ path, request, _ = inputs(tmp_path)+ request['audio'] = [{'id': 'hit', 'source': 'audio/sound.json'}]+ path.write_text(json.dumps(request))+ return path, request+++def test_version_1_pack_with_sound_keeps_its_files_and_bytes(tmp_path):+ path, _ = with_sound(tmp_path)+ out = tmp_path/'out'+ result = pack(path, out)+ assert sorted(p.name for p in out.iterdir()) == V1_AUDIO_FILES+ manifest = (out/'game-pack.json').read_bytes()+ assert hashlib.sha256(manifest).hexdigest() == V1_AUDIO_MANIFEST_SHA256+ assert json.loads(manifest)['version'] == 1+ with Image.open(out/'atlas-000.png') as page:+ assert hashlib.sha256(page.convert('RGBA').tobytes()).hexdigest() == V1_AUDIO_PAGE_PIXELS_SHA256+ for fmt in ('ogg', 'm4a'):+ assert (out/f'audio-hit.{fmt}').read_bytes() == f'synthetic-{fmt}'.encode()+ assert hashlib.sha256((out/'sprite-gen-audio-v2.mjs').read_bytes()).hexdigest() == result['audio']['hit']['player']['sha256']+++def test_version_2_pack_with_sound_adds_only_the_tile_files(tmp_path):+ path, request = with_sound(tmp_path)+ pack(path, tmp_path/'v1')+ Image.new('RGBA', (8, 8), 'blue').save(tmp_path/'ground.png')+ request.update(version=2, tiles=[{'id': 'ground', 'source': 'ground.png', 'display': {'width': 16}}])+ path.write_text(json.dumps(request))+ result = pack(path, tmp_path/'v2')+ v1 = {p.name: p.read_bytes() for p in (tmp_path/'v1').iterdir()}+ v2 = {p.name: p.read_bytes() for p in (tmp_path/'v2').iterdir()}+ assert sorted(v2) == sorted([*v1, 'tile-ground.png', 'tile-ground.webp'])+ for name in ('audio-hit.ogg', 'audio-hit.m4a', 'sprite-gen-audio-v2.mjs', 'atlas-000.png', 'atlas-000.webp'):+ assert v2[name] == v1[name], name+ assert result['version'] == 2 and list(result['audio']) == ['hit']+ assert result['tiles']['ground']['image'] == 'tile-ground.png'