Skip to content

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.py
index fae54dd..5fe9737 100644
--- a/sprite_gen/compose/game_pack.py
+++ b/sprite_gen/compose/game_pack.py
@@ -21,7 +21,8 @@ from PIL import Image
from sprite_gen.audio.manifest import load as load_sound
from 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 np
from sprite_gen.spec.assets import finite, load_asset, load_asset_states
from 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))
+ continue
size = (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, sources
diff --git a/sprite_gen/frames/ui_kit.py b/sprite_gen/frames/ui_kit.py
index 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's
alpha 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 = 96
GUIDE_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: str
where: str
what: 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 = None
LAYOUT = (
@@ -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_h
return {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 = None
if 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] = element
records[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__.py
index 32bf517..cd612dc 100644
--- a/sprite_gen/gen/__init__.py
+++ b/sprite_gen/gen/__init__.py
@@ -105,7 +105,8 @@ _CODEX_PROBE_TIMEOUT_SECONDS = 15
LAYOUT_GUIDE_LONG_EDGE = 1024
LAYOUT_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 None
return 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.text
for 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: l
def 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 prompt
names 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 = N
parts.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")