Skip to content

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.md
index 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.py
index 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=MAX
document = 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 = None
if 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_sources
names = [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=MAX
sources.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"]] = module
diff --git a/tests/compose/test_game_pack_audio.py b/tests/compose/test_game_pack_audio.py
index 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'