Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
docs: slice-sheet sheet scale, contain fit and report; game-pack images take the reported anchor
Soohong Kim0a0aa048df07
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex cafef3f..ee4c14a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,7 +8,9 @@ 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` (or `--report PATH`, which must end in `.json`; each element's `file` is its PNG's path from the report's directory, so a report written outside `--out-dir` still finds its elements): 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; a report in, beside, below or above `--out-dir` names the PNGs from its own directory and packs the same bytes), `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`.+- **New: `slice-sheet --scale sheet` keeps the sizes a sheet was drawn at, and `--fit contain` keeps every cut whole.** The default gives each cell's main subject the target height on its own, so the props of one sheet came out the same height, and lets the canvas cut whatever that scale puts past its edge, so a subject wider than the canvas lost its sides. `--scale sheet` takes one factor for the whole sheet (the tallest main subject reaches `--target-height`), so a prop drawn twice as tall stays twice as tall. `--fit contain` lowers the factor until the whole cut fits the canvas, with the main subject still centred on its base; with `--scale sheet` the sheet takes the smallest factor any cell fits at. Every cell of a sheet keeps one canvas size, so a game pack that gives the cells one `display` height keeps their sizes too ([sheet-slicing](docs/sheet-slicing.md#props-and-icons-sheet-scale-and-contain-fit)).+- **New: `slice-sheet` writes `<prefix>slice-sheet.json`.** It names the scale and fit, the sheet's factor and where it came from, and per cell the factor, the main subject's size on the sheet and on the canvas, the cut's box on the canvas, the `anchor` (the centre of the main subject's base, ready for a game pack's `images[].anchor`) and `clipped_px`, the pixels the canvas cut ([report](docs/sheet-slicing.md#report)). A run also prints a line for each cell the canvas cut. The PNGs of a default run are unchanged byte for byte; a sheet with an empty cell now fails before any cell is written, where it used to write the cells before it.+- **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; a report in, beside, below or above `--out-dir` names the PNGs from its own directory and packs the same bytes), `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) the `--layout-guide ui-kit` cases in `tests/gen/test_layout_guide.py`, and `tests/frames/test_slice_sheet_scale.py` (synthetic sheets: drawn heights kept within a pixel with `--scale sheet`, after the alpha cleanup too; a 2:1 subject whole on a square canvas with `--fit contain` while the default still cuts it and says so; one factor every cut fits; sliced cells packed as game-pack `images` keep one size and stand on the reported anchor; refusals).- Bump audio processing recipe to version 4, measure BS.1770-4 loudness over normalized PCM frames and gated blocks, support a peak-limited loudness goal, normalize loudnorm-unanalysable short clips via limiter passes instead of refusing them, encode AAC using `-aac_coder fast`, record `normalization.pcm_lufs` and `pcm_true_peak_dbtp` required to load version 4 bundles, keep recipe version 3 bundles loadable in game packs by their own rule (target loudness, decoded files re-measured with loudnorm), reject recipe version 1-2 bundles, and reject recipe version 1-3 output directories in `sprite-gen sound` while reusing cached provider audio.- Bump audio processing recipe to version 3, require `ffprobe` on `PATH`, export M4A with `-movie_timescale 48000`, and validate AAC stream duration with `ffprobe`.diff --git a/SKILL.md b/SKILL.mdindex a3e6c2f..5f1e992 100644--- a/SKILL.md+++ b/SKILL.md@@ -121,7 +121,7 @@ hold the arms still, and check the loop with `handed-check --state walk`.| Background recipe or repeating tile | existing `gen` / `cutout`, then optional `background-tile` | [asset-tools](docs/asset-tools.md#background-recipe) || Ground tile that repeats both ways | `gen` (opaque), then `background-tile --axis xy` | [asset-tools](docs/asset-tools.md#both-axes-a-ground-tile) || Game UI kit: panel, buttons, card, HP/XP bar frames, timer badge as nine-slice elements | `gen --transparent --aspect-ratio 1:1 --layout-guide ui-kit`, then `ui-kit` | [ui-kit](docs/ui-kit.md) |-| Props or icons on a transparent sheet | `slice-sheet --chroma-key none --alpha-floor 64` | [sheet-slicing](docs/sheet-slicing.md#transparent-sheets) |+| Props or icons on a transparent sheet | `slice-sheet --chroma-key none --alpha-floor 64`, props with `--scale sheet --fit contain`, icons with `--fit contain` | [sheet-slicing](docs/sheet-slicing.md#props-and-icons-sheet-scale-and-contain-fit) || Painted props, a ground tile and a UI kit in a game pack | `game-pack` request version 2 (`images`, `tiles`, `ui`) | [game-pack](docs/game-pack.md#version-2-images-tiles-and-ui) || Standalone projected shadow | `shadow` | [asset-tools](docs/asset-tools.md#projected-shadows) || Duplicate poses, foot contact and stride measurement | `inspect-motion` | [asset-tools](docs/asset-tools.md#motion-and-contact-evidence) |diff --git a/docs/game-pack.md b/docs/game-pack.mdindex 70d54d6..d40c453 100644--- a/docs/game-pack.md+++ b/docs/game-pack.md@@ -195,6 +195,7 @@ Version 2 adds three sections for painted scene art: single images such as props* `assets` and `audio` keep their version 1 meaning. In version 2, `assets` may be empty or absent; the request must still declare at least one asset, image, tile, UI kit or icon.* Every `id` uses the asset name characters (`[A-Za-z0-9_.-]`) and is unique within its section.* `images[]`: one PNG each (a static image or a one-frame descriptor; more frames are refused). `display` takes exactly one of `width` or `height` (no `body_height`), and `resample` works as for assets. `anchor` is `[x, y]` in source pixels and defaults to the bottom centre of the image. `footprint` is optional: an explicit `{x, y, w, h}` rectangle in source pixels, or `"base"` for the measured base described below.+* Props cut from one sheet by [`slice-sheet`](sheet-slicing.md#props-and-icons-sheet-scale-and-contain-fit) share one canvas size, so giving every cell of the sheet the same `display` height keeps the sizes the sheet gave them (`--scale sheet`). The [slice-sheet report](sheet-slicing.md#report) states each cell's `anchor`, the centre of its main subject's base, in the PNG's own pixels: pass it as the entry's `anchor` as it is.* `tiles[]`: one PNG each, ideally a seamless tile from [`background-tile --axis xy`](asset-tools.md#repeating-tiles). `display` takes exactly one of `width` or `height`: the size of one tile on screen. The tile's pixels are never resampled: the pack stores the source pixels and states both sizes.* `ui.kit`: the JSON report a [`ui-kit`](ui-kit.md) run wrote. Every element it lists becomes a nine-slice entry, with the element PNGs it names (paths relative to the report). `ui.scale` (default `1`, positive) resizes every kit element by the same factor, so the kit stays one consistent set.* `ui.icons[]`: fixed images such as upgrade or weapon icons, with `id`, `source` and `display` as for `images` (no anchor or footprint).diff --git a/docs/sheet-slicing.md b/docs/sheet-slicing.mdindex bb62c83..85c0466 100644--- a/docs/sheet-slicing.md+++ b/docs/sheet-slicing.md@@ -7,7 +7,9 @@ image containing a COLSxROWS grid of the same character (expressions, poses,outfits) into per-cell RGBA cuts on a fixed canvas with a shared feetbaseline and a normalized subject height. Built for dialogue cut-inportraits (立ち絵); works for any "same subject, N variants in one sheet"-generation.+generation. For a sheet of different props or icons, `--scale sheet` keeps+the sizes they were drawn at and `--fit contain` keeps every cut whole+([Props and icons](#props-and-icons-sheet-scale-and-contain-fit)).This is NOT the component-row animation pipeline. Rows animate one stateover time; a sheet enumerates variants of one standing subject. Use@@ -73,6 +75,78 @@ sprite-gen slice-sheet --sheet props.png --out-dir props/ --chroma-key none --al--grid 3x2 --names pillar,statue,shrub,lantern,gravestone,fountain --prefix prop_```+## Props and icons: sheet scale and contain fit++The default suits a character's variants: each cell's main subject is scaled to `--target-height` on its own,+and the canvas cuts whatever that scale puts past its edge. A sheet of different things needs two other rules,+each a flag:++- **`--scale sheet`** takes one factor for the whole sheet: the tallest main subject reaches `--target-height`+ and every other cell is scaled by the same factor. A prop drawn twice as tall as another stays twice as tall,+ within a pixel. The default `--scale cell` gives every cell its own factor.+- **`--fit contain`** lowers the factor until the whole cut, every part the cell kept, fits the canvas: the main+ subject stays centred with its base on `--baseline-y`, and nothing past an edge is cut. A wide icon on a square+ canvas is scaled down to the canvas width instead of losing its sides. With `--scale sheet` the sheet takes the+ smallest factor any of its cells fits at, so the relative sizes stay. The default `--fit none` keeps the factor+ and lets the canvas cut. `contain` needs `--baseline-y` inside the canvas, and a part drawn below the main+ subject's base needs room under the baseline; a cell that cannot fit is refused by name.++```bash+# props: drawn sizes kept, nothing cut, feet on the canvas floor+sprite-gen slice-sheet --sheet props.png --out-dir props/ --chroma-key none --alpha-floor 64 \+ --grid 3x2 --names pillar,statue,shrub,lantern,gravestone,fountain --prefix prop_ \+ --cell-width 512 --cell-height 256 --baseline-y 256 --target-height 240 --scale sheet --fit contain+# icons: each icon as tall as the target unless it is wide, then as wide as the canvas+sprite-gen slice-sheet --sheet icons.png --out-dir icons/ --chroma-key none --alpha-floor 64 \+ --grid 4x3 --cell-width 256 --cell-height 256 --baseline-y 236 --target-height 216 --fit contain+```++Every cell of a sheet is cut on the same canvas, so a [game pack](game-pack.md#version-2-request) that gives each+cell the same `display` height scales them all by the same amount and the sizes stay relative there too. The alpha+cleanup (`--alpha-floor`) runs before anything is measured, so the factor is taken on the cleaned sheet and applies to+every cell alike.++## Report++Every run writes `<out-dir>/<prefix>slice-sheet.json`:++```json+{+ "kind": "sprite-gen-slice-sheet",+ "version": 1,+ "sheet": "props.png",+ "grid": [3, 2],+ "canvas": {"w": 512, "h": 256},+ "baseline_y": 256.0,+ "target_height": 240.0,+ "scale": "sheet",+ "fit": "contain",+ "factor": 0.8,+ "factor_from": {"rule": "target_height", "cell": "fountain"},+ "alpha_cleanup": "prop_alpha-cleanup.json",+ "cells": [+ {"name": "pillar", "file": "prop_pillar.png", "factor": 0.8, "factor_from": "target_height",+ "subject": {"sheet": {"w": 120, "h": 260}, "canvas": {"w": 96, "h": 208}},+ "box": {"x": 208, "y": 48, "w": 96, "h": 208}, "anchor": [256.0, 256.0],+ "clipped_px": 0, "parts": 1}+ ]+}+```++- `scale` and `fit` name the rules the run used. `factor` is the one factor of a `sheet` run and `factor_from`+ says where it came from: `target_height` of the tallest cell, or `fit` of the cell that needed the smallest+ factor. Both are `null` for a `cell` run, where each cell has its own.+- Per cell, in reading order: `file` is the PNG beside the report; `factor` and `factor_from` (`target_height` or+ `fit`) are that cell's; `subject` is the main subject's size on the sheet and scaled onto the canvas; `box` is+ where the whole cut (every part kept) lies on the canvas; `anchor` is `[x, y]` on the canvas, the centre of the+ main subject's base, the point it stands on; `clipped_px` counts the cut's pixels with any alpha that fell past+ the canvas edge (always `0` with `contain`; the run also prints a line for each cell the canvas cut); `parts` is+ how many parts the cell kept.+- `anchor` goes into a game pack's `images[].anchor` as it is: it is in the PNG's own pixels. When `--baseline-y`+ equals `--cell-height`, the pack's default bottom-centre anchor is the same point.++The PNGs of a default run (`--scale cell --fit none`) are byte for byte those of the version before these flags.+## Geometry rules (and the field failures they encode)Each rule below exists because the naive version shipped a visible defect@@ -105,10 +179,15 @@ during the a cut-in overhaul (2026-07-09):[video-pipeline.md](video-pipeline.md) "Cells"), so the scaled figure has no rim or key tint at its edge thatthe sliced figure did not have.5. **Feet on the baseline.** The main figure's lowest pixel lands on- `--baseline-y`; effects above the head never shift the feet.+ `--baseline-y`; effects above the head never shift the feet. Under the+ default `--fit none` a cut that crosses the canvas's top or left edge is+ moved back inside and the canvas cuts it on the other side; the report's+ `anchor`, `box` and `clipped_px` say where it landed and what was cut.+ `--fit contain` scales it until it fits instead.6. **Fail loud on empty cells.** A cell with no subject after extractionraises instead of writing a blank — a cropped or mis-gridded sheet must- be regenerated, not silently absorbed.+ be regenerated, not silently absorbed. Every cell is measured before any+ is written, so a failing sheet writes no cells.## Prompting the sheet