Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
feat(ui-kit): a 2:3 sheet holds the whole kit: bar fills fitted to their frame's content area, a slot, a badge, on/off pips and a joystick base and knob; game-pack stores each fill at its frame's content area
Soohong Kim4c455d048f3e
diff --git a/sprite_gen/compose/game_pack.py b/sprite_gen/compose/game_pack.pyindex fae54dd..5fe9737 100644--- a/sprite_gen/compose/game_pack.py+++ b/sprite_gen/compose/game_pack.py@@ -21,7 +21,8 @@ from PIL import Imagefrom sprite_gen.audio.manifest import load as load_soundfrom sprite_gen.audio.playback import player as audio_player-from sprite_gen.frames.ui_kit import REPORT_KIND as UI_KIT_KIND, STRETCHES, element_path, measure_insets+from sprite_gen.frames.ui_kit import (REPORT_KIND as UI_KIT_KIND, STRETCHES, content_rect, element_path,+ measure_insets)from sprite_gen._deps import npfrom sprite_gen.spec.assets import finite, load_asset, load_asset_statesfrom sprite_gen.util.resample import resize_cell@@ -221,6 +222,43 @@ def _sides(record, field, key):return sides+def _ends_kept(cell, insets, width):+ """``cell`` as a three-slice drawn ``width`` wide: its two end slices as they are, its middle columns+ repeated or dropped (nearest), never blended."""+ if cell.width == width:+ return cell+ left, right = insets["left"], insets["right"]+ stored = Image.new("RGBA", (width, cell.height), (0, 0, 0, 0))+ stored.paste(cell.crop((0, 0, left, cell.height)), (0, 0))+ middle = cell.crop((left, 0, cell.width - right, cell.height))+ stored.paste(middle.resize((width - left - right, cell.height), Image.Resampling.NEAREST), (left, 0))+ stored.paste(cell.crop((cell.width - right, 0, cell.width, cell.height)), (width - right, 0))+ return stored+++def _fill(name, record, image, frame, page_size):+ """A fill stored at its frame's content rectangle (docs/game-pack.md "Version 2 manifest"): resized by the+ one factor that makes it as tall as the rectangle, then drawn as wide as it with its ends kept."""+ key = f"ui/{_name(name)}"+ rect = content_rect(frame)+ factor = rect["h"] / image.height+ cell = resize_cell(image, (max(1, round(image.width * factor)), rect["h"]))+ insets = {side: _scaled_up(record["insets"][side], factor) for side in SIDES}+ measured, _notes = measure_insets(cell, "x")+ insets = {side: max(insets[side], measured[side]) for side in SIDES}+ if insets["left"] + insets["right"] >= min(cell.width, rect["w"]):+ raise ValueError(f"{key}: scaled to the height of {record['inside']['element']}'s content area, its fixed "+ "ends are wider than that area")+ padding = {side: _scaled_up(record["padding"][side], factor) for side in SIDES}+ if padding["left"] + padding["right"] >= rect["w"] or padding["top"] + padding["bottom"] >= rect["h"]:+ raise ValueError(f"{key}: in its frame's content area the padding leaves no content area")+ size = (rect["w"], rect["h"])+ _fits(key, size, page_size)+ entry = {"frame": key, "size": {"w": size[0], "h": size[1]}, "stretch": "x", "insets": insets,+ "padding": padding, "inside": {"element": record["inside"]["element"], "rect": rect}}+ return entry, (key, _ends_kept(cell, insets, size[0]), (size[0] / 2, size[1] / 2))++def _ui_kit(path, scale, page_size):"""Nine-slice entries and atlas frames from a `ui-kit` report (docs/ui-kit.md "Report")."""report = json.loads(path.read_text(encoding="utf-8"))@@ -229,7 +267,7 @@ def _ui_kit(path, scale, page_size):elements = report.get("elements")if not isinstance(elements, dict) or not elements:raise ValueError("ui-kit report lists no elements")- entries, frames, sources = {}, [], {path}+ entries, frames, sources, fills = {}, [], {path}, []for name, record in elements.items():key = f"ui/{_name(name)}"if not isinstance(record, dict) or record.get("stretch") not in STRETCHES:@@ -245,6 +283,16 @@ def _ui_kit(path, scale, page_size):image = sequence.frames[0]if record.get("size") != {"w": image.width, "h": image.height}:raise ValueError(f"{key}: the report's size does not match {record['file']}")+ sources.update(sequence.source_files)+ if "inside" in record:+ # a fill takes its size from its frame's stored content area, so it is packed after every frame+ inside = record["inside"]+ if not isinstance(inside, dict) or not isinstance(inside.get("element"), str):+ raise ValueError(f"{key}: inside must name the element the fill goes in")+ if stretch != "x":+ raise ValueError(f"{key}: a fill stretches in width only (stretch x), not {stretch}")+ fills.append((name, record, image))+ continuesize = (max(1, round(image.width * scale)), max(1, round(image.height * scale)))_fits(key, size, page_size)cell = image if size == image.size else resize_cell(image, size)@@ -263,7 +311,13 @@ def _ui_kit(path, scale, page_size):frames.append((key, cell, (size[0] / 2, size[1] / 2)))entries[name] = {"frame": key, "size": {"w": size[0], "h": size[1]}, "stretch": stretch,"insets": insets, "padding": padding}- sources.update(sequence.source_files)+ frame_names = set(entries)+ for name, record, image in fills:+ target = record["inside"]["element"]+ if target not in frame_names:+ raise ValueError(f"ui/{_name(name)}: inside names {target}, which is not a frame of this report")+ entries[name], frame = _fill(name, record, image, entries[target], page_size)+ frames.append(frame)return entries, frames, sourcesdiff --git a/sprite_gen/frames/ui_kit.py b/sprite_gen/frames/ui_kit.pyindex 9e4166e..a4f2658 100644--- a/sprite_gen/frames/ui_kit.py+++ b/sprite_gen/frames/ui_kit.py@@ -2,10 +2,13 @@"""Split a transparent UI kit sheet drawn on the fixed layout into nine-slice elements.docs/ui-kit.md is the contract. One table (`LAYOUT`) is the layout: `gen --layout-guide ui-kit`-draws it (`draw_guide`) and says it (`guide_text`), and the splitter cuts along it. The sheet's+draws it (`draw_guide`) and says it (`guide_text`), and the splitter cuts along it. A sheet's shape+says which part of the table it holds (`SHEETS`): a square sheet the seven frames, a 2:3 sheet the+same frames at the same places and the fills, slot, badge, pips and joystick below them. The sheet'salpha haze is cleared first (`alpha_floor.clear_haze`), parts are assigned to boxes by centroid,-and each element's insets and content padding are measured on its own pixels. The report names each-element PNG by its path from the report's own directory (`report_file`, `element_path`).+and each element's insets and content padding are measured on its own pixels; a fill is fitted to its+bar frame's content area. The report names each element PNG by its path from the report's own+directory (`report_file`, `element_path`)."""from __future__ import annotations@@ -35,6 +38,7 @@ PADDING_SPAN = 96GUIDE_BACKGROUND = (0xF6, 0xF6, 0xF6)GUIDE_BOX = (0x2F, 0x80, 0xED)STRETCHES = ("xy", "x", "none")+SIDES = ("left", "right", "top", "bottom")REPORT_KIND = "sprite-gen-ui-kit"@@ -45,6 +49,11 @@ class Slot:stretch: strwhere: strwhat: str+ # Padding is measured only for an element that holds content (text, digits, an icon, a bar's fill);+ # the others get 0 on every side, as insets are 0 along an axis the element keeps.+ content: bool = True+ # A fill: the bar frame whose content area it fills (docs/ui-kit.md "Fills").+ inside: str | None = NoneLAYOUT = (@@ -62,33 +71,90 @@ LAYOUT = ("an empty horizontal experience bar frame"),Slot("timer_badge", (48, 816, 160, 160), "none", "the small square box at the bottom left","a small round badge with an empty centre"),+ # The band below the square, on the 2:3 sheet only.+ Slot("hp_bar_fill", (48, 1024, 608, 64), "x", "the long thin box at the top left of the band",+ "the health bar's fill, a solid horizontal strip", content=False, inside="hp_bar_frame"),+ Slot("xp_bar_fill", (48, 1136, 608, 64), "x", "the long thin box below it",+ "the experience bar's fill, the same kind of strip in its own colour", content=False,+ inside="xp_bar_frame"),+ Slot("slot", (48, 1248, 192, 192), "xy", "the square box below them at the left",+ "a square item slot frame with an empty centre"),+ Slot("badge", (288, 1248, 176, 112), "xy", "the small wide box to its right",+ "a small counter plate with an empty centre"),+ Slot("pip_on", (512, 1248, 96, 96), "none", "the small square box to the right of that",+ "a small round indicator dot, lit", content=False),+ Slot("pip_off", (512, 1392, 96, 96), "none", "the small square box below it",+ "the same dot unlit", content=False),+ Slot("joystick_base", (704, 1024, 272, 272), "none", "the large square box at the right of the band",+ "a round touch joystick base", content=False),+ Slot("joystick_knob", (768, 1344, 144, 144), "none", "the smaller square box below it",+ "the joystick's round knob", content=False),)+FRAME_COUNT = 7+# Sheet shape -> (the size the layout's boxes are given at, the slots it holds). The 2:3 sheet keeps the+# square's seven boxes where they are and adds the band below them, so a square sheet cuts as it always has.+SHEETS = {+ "square": ((REFERENCE, REFERENCE), LAYOUT[:FRAME_COUNT]),+ "tall": ((REFERENCE, REFERENCE * 3 // 2), LAYOUT),+}+++def sheet_layout(size: tuple[int, int]) -> tuple[tuple[int, int], tuple[Slot, ...]]:+ """The reference size and the slots of a sheet of ``size``: square, or 2:3, each within 1 %."""+ width, height = size+ for (ref_w, ref_h), slots in SHEETS.values():+ if abs(width * ref_h - height * ref_w) <= 0.01 * max(width * ref_h, height * ref_w):+ return (ref_w, ref_h), slots+ raise ValueError(f"a UI kit sheet must be square (1:1, the frames) or 2:3 (the whole kit); "+ f"this one is {width}x{height}")def boxes(size: tuple[int, int]) -> dict[str, tuple[int, int, int, int]]:- """The layout's boxes as (x, y, w, h) in pixels of a sheet of ``size``, in layout order."""+ """The boxes a sheet of ``size`` holds, as (x, y, w, h) in its pixels, in layout order."""+ (ref_w, ref_h), slots = sheet_layout(size)width, height = size- sx, sy = width / REFERENCE, height / REFERENCE+ sx, sy = width / ref_w, height / ref_hreturn {slot.name: (round(slot.box[0] * sx), round(slot.box[1] * sy),- round(slot.box[2] * sx), round(slot.box[3] * sy)) for slot in LAYOUT}+ round(slot.box[2] * sx), round(slot.box[3] * sy)) for slot in slots}def _rect(x: int, y: int, w: int, h: int) -> dict[str, int]:return {"x": int(x), "y": int(y), "w": int(w), "h": int(h)}-def guide_text() -> str:- """The prompt's half of the guide: what to draw in each box and how, in layout order."""- places = "; ".join(f"in {slot.where}, {slot.what}" for slot in LAYOUT)+def _places(slots: tuple[Slot, ...]) -> str:+ return "; ".join(f"in {slot.where}, {slot.what}" for slot in slots)+++def guide_text(size: tuple[int, int] = (REFERENCE, REFERENCE)) -> str:+ """The prompt's half of the guide for a sheet of ``size``: what to draw in each box and how, in layout order."""+ _, slots = sheet_layout(size)+ if len(slots) == FRAME_COUNT:+ return (+ "Layout: the last attached image is a layout guide, not part of the artwork. It shows "+ f"{len(slots)} blue boxes on a grey sheet. Draw exactly one user interface element inside each box, "+ "filling most of its box without touching the box's edges, and leave everything outside the boxes "+ f"empty and transparent: {_places(slots)}. Every frame, button and bar has straight, even edges "+ "between its corners, so it can be stretched along them: put ornaments only in the corners, and on "+ "the bars only at their two ends. Leave every centre empty: no text, no letters, no numbers, no icons "+ "and no fill inside the bars. Do not reproduce the layout guide itself: no boxes, guide lines, guide "+ "colors or the guide's grey background may appear in the output."+ )+ frames, band = slots[:FRAME_COUNT], slots[FRAME_COUNT:]return ("Layout: the last attached image is a layout guide, not part of the artwork. It shows "- f"{len(LAYOUT)} blue boxes on a grey sheet. Draw exactly one user interface element inside each box, "- "filling most of its box without touching the box's edges, and leave everything outside the boxes "- f"empty and transparent: {places}. Every frame, button and bar has straight, even edges between its "- "corners, so it can be stretched along them: put ornaments only in the corners, and on the bars only "- "at their two ends. Leave every centre empty: no text, no letters, no numbers, no icons and no fill "- "inside the bars. Do not reproduce the layout guide itself: no boxes, guide lines, guide colors or the "- "guide's grey background may appear in the output."+ f"{len(slots)} blue boxes on a grey sheet: {len(frames)} in the square at the top and {len(band)} in the "+ "band below it. Draw exactly one user interface element inside each box, filling most of its box without "+ "touching the box's edges, and leave everything outside the boxes empty and transparent. In the square "+ f"at the top: {_places(frames)}. In the band below it: {_places(band)}. Every frame, button, bar, fill, "+ "slot and plate has straight, even edges between its corners, so it can be stretched along them: put "+ "ornaments only in the corners, and on the bars and the fills only at their two ends. Each fill is one "+ "solid strip, the same colour all along its length (it may shade from its top edge to its bottom edge), "+ "with no marks, segments or highlights along it. Leave the centre of every frame, button, bar frame, slot "+ "and plate empty: no text, no letters, no numbers, no icons and no fill inside the bar frames. The two "+ "dots, the joystick base and the knob are round and seen straight from the front; the two dots are the "+ "same size. Do not reproduce the layout guide itself: no boxes, guide lines, guide colors or the guide's "+ "grey background may appear in the output.")@@ -257,8 +323,7 @@ def split_ui_kit(image: Image.Image, *, alpha_floor: int = 64,place, ``<out-dir>/ui-kit.json`` (each ``file`` is ``<element>.png``), without the sheet path."""rgba = image.convert("RGBA")width, height = rgba.size- if abs(width - height) > 0.01 * max(width, height):- raise ValueError(f"a UI kit sheet must be square (1:1); this one is {width}x{height}")+ _, slots = sheet_layout((width, height))cleanup = Noneif alpha_floor:rgba, cleanup = clear_haze(rgba, floor=alpha_floor, edge=alpha_edge)@@ -282,7 +347,7 @@ def split_ui_kit(image: Image.Image, *, alpha_floor: int = 64,assigned[owner].append(part)elements: dict[str, Image.Image] = {}records: dict[str, Any] = {}- for slot in LAYOUT:+ for slot in slots:parts = assigned[slot.name]if not parts:raise ValueError(f"{slot.name}: its box holds no element; generate the sheet again")@@ -296,7 +361,7 @@ def split_ui_kit(image: Image.Image, *, alpha_floor: int = 64,cut[y - y0, a - x0:b - x0] = pixels[y, a:b]element = Image.fromarray(cut)insets, inset_notes = measure_insets(element, slot.stretch)- padding, padding_notes = measure_padding(element)+ padding, padding_notes = measure_padding(element) if slot.content else (dict.fromkeys(SIDES, 0), [])reasons += [f"{slot.name}: {note}" for note in inset_notes + padding_notes]elements[slot.name] = elementrecords[slot.name] = {@@ -309,6 +374,10 @@ def split_ui_kit(image: Image.Image, *, alpha_floor: int = 64,"padding": padding,"parts": len(parts),}+ for slot in slots:+ if slot.inside is not None:+ records[slot.name]["inside"], note = fit_inside(records[slot.name], records[slot.inside], slot.inside)+ reasons += [f"{slot.name}: {note}"] if note else []report = {"kind": REPORT_KIND,"version": 1,@@ -323,6 +392,25 @@ def split_ui_kit(image: Image.Image, *, alpha_floor: int = 64,return elements, report+def content_rect(record: dict[str, Any]) -> dict[str, int]:+ """The content rectangle of an element record (its size less its padding), from its top-left corner."""+ pad, size = record["padding"], record["size"]+ return _rect(pad["left"], pad["top"], size["w"] - pad["left"] - pad["right"],+ size["h"] - pad["top"] - pad["bottom"])+++def fit_inside(fill: dict[str, Any], frame: dict[str, Any], name: str) -> tuple[dict[str, Any], str | None]:+ """A fill's ``inside``: the frame it fills, that frame's content rectangle and the factor that makes the+ fill exactly as tall as it (docs/ui-kit.md "Fills"), and a review note when its fixed ends would not fit."""+ rect = content_rect(frame)+ scale = rect["h"] / fill["size"]["h"]+ note = None+ if (fill["insets"]["left"] + fill["insets"]["right"]) * scale >= rect["w"]:+ note = (f"scaled to the height of {name}'s content area, its fixed ends are wider than that area; "+ "a full bar would overflow it")+ return {"element": name, "rect": rect, "scale": round(scale, 6)}, note++def report_file(report: Path, png: Path) -> str:"""The ``file`` a report at ``report`` gives ``png``: its path from the report's directory, ``/``-separated."""return Path(os.path.relpath(png, Path(report).parent)).as_posix()diff --git a/sprite_gen/gen/__init__.py b/sprite_gen/gen/__init__.pyindex 32bf517..cd612dc 100644--- a/sprite_gen/gen/__init__.py+++ b/sprite_gen/gen/__init__.py@@ -105,7 +105,8 @@ _CODEX_PROBE_TIMEOUT_SECONDS = 15LAYOUT_GUIDE_LONG_EDGE = 1024LAYOUT_GUIDE_NAME = "layout-guide.png"# `--layout-guide ui-kit` attaches the UI kit layout instead (`sprite_gen.frames.ui_kit`, docs/ui-kit.md):-# one box per element, the boxes `ui-kit` later cuts along. The bare flag is the figure guide.+# one box per element, the boxes `ui-kit` later cuts along; square for the frames, 2:3 for the whole kit.+# The bare flag is the figure guide.LAYOUT_GUIDE_KINDS = ("figure", "ui-kit")CROWN_LINE = "#ff7a00"CROWN_MARK = "#ffb15c"@@ -200,10 +201,15 @@ def layout_guide_kind(value: bool | str | None) -> str | None:def ui_kit_guide_size(aspect_ratio: str | None) -> tuple[int, int]:- """The UI kit guide is square: its boxes are the ones `ui-kit` cuts a square sheet along."""+ """The UI kit guide is square (the frames) or 2:3 (the whole kit): the sheet shapes `ui-kit` cuts along."""+ from sprite_gen.frames import ui_kit+width, height = layout_guide_size(aspect_ratio)- if width != height:- raise SystemExit(f"gen: the ui-kit layout guide is square; use --aspect-ratio 1:1 (got {aspect_ratio})")+ try:+ ui_kit.sheet_layout((width, height))+ except ValueError:+ raise SystemExit("gen: the ui-kit layout guide is square (1:1, the frames) or 2:3 (the whole kit); "+ f"use --aspect-ratio 1:1 or 2:3 (got {aspect_ratio})") from Nonereturn width, height@@ -432,7 +438,7 @@ def generate_image(parts = still_prompt(prompt, view=view, facing=facing, handed=handed, body_plan=body_plan, refs=bool(refs),key=chroma_key if strategy_source == STRATEGY_SOURCE_REFS else None,layout=layout_guide_cell(aspect_ratio) if guide_kind == "figure" else None,- ui_kit_guide=guide_kind == "ui-kit")+ ui_kit_guide=ui_kit_guide_size(aspect_ratio) if guide_kind == "ui-kit" else None)prompt = parts.textfor line in prompt_parts.note_lines(parts):print(f"[gen] {line}", file=sys.stderr)@@ -609,7 +615,8 @@ def _check_view(view: str | None, facing: str | None, facing_fix: str, handed: ldef still_prompt(prompt: str, *, view: str | None = None, facing: str | None = None,handed: list[handed_mod.Handed] | None = None, body_plan: list[Body] | None = None,refs: bool = False, key: str | None = None,- layout: dict[str, Any] | None = None, ui_kit_guide: bool = False) -> prompt_parts.Prompt:+ layout: dict[str, Any] | None = None,+ ui_kit_guide: tuple[int, int] | None = None) -> prompt_parts.Prompt:"""The prompt a still is drawn from: the caller's text, then the engine's pieces (`prompt_parts.Prompt.add`;without `handed` or `body_plan`, 2.22.0's prompt to the byte). In order:@@ -621,7 +628,7 @@ def still_prompt(prompt: str, *, view: str | None = None, facing: str | None = N- `key` (green / magenta, a ref run `auto` planned to key): the key background line, unless the promptnames a key background already;- `layout` (the `--layout-guide` cell): where the guide's lines are; `ui_kit_guide`- (`--layout-guide ui-kit`): what to draw in each box of the UI kit layout.+ (`--layout-guide ui-kit`, the guide's size): what to draw in each box of the UI kit layout."""figures = body_mod.figures(body_plan)parts = prompt_parts.Prompt(prompt, caller=f"{prompt} {figures}" if figures else None)@@ -639,10 +646,10 @@ def still_prompt(prompt: str, *, view: str | None = None, facing: str | None = Nparts.add("key-background", chroma_mod.KEY_BACKGROUND_TEXT[key], key=key)if layout is not None:parts.add("layout", layout_guide_text(layout))- if ui_kit_guide:+ if ui_kit_guide is not None:from sprite_gen.frames import ui_kit- parts.add("layout", ui_kit.guide_text())+ parts.add("layout", ui_kit.guide_text(ui_kit_guide))return parts@@ -803,8 +810,9 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:"attach a layout guide after any --ref. Bare or `figure`: a one-slot guide (frame, inner safe ""area at the row guide's 9.4 %% margin, center line) asking for the whole subject inside the ""safe area, with room above the head and below the feet; drawn for --aspect-ratio, square "- "without one. `ui-kit`: the UI kit layout, one box per element, for `sprite-gen ui-kit` "- "(square only)"+ "without one. `ui-kit`: the UI kit layout, one box per element, for `sprite-gen ui-kit`: square "+ "(--aspect-ratio 1:1 or none) for the frames, 2:3 for the whole kit with bar fills, slot, badge, "+ "pips and joystick"),)parser.add_argument("--white-check", type=Path, help="write a white-composite check image")