Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
refactor(pixel-draw): the four kinds are named once, SPRITE, ICON, TILE and EFFECT unpacked from KINDS in gen/pixel_gates.py, and every kind branch and default in pixel_draw and pixel_gates reads them
Soohong Kima1b81ac87fc3
diff --git a/sprite_gen/gen/pixel_draw.py b/sprite_gen/gen/pixel_draw.pyindex b85d2fd..aa7d5ce 100644--- a/sprite_gen/gen/pixel_draw.py+++ b/sprite_gen/gen/pixel_draw.py@@ -64,7 +64,7 @@ from . import anthropic_api as apifrom . import claude_login, refusalfrom .anthropic_api import ApiError, Replyfrom .base import announce_api_billing, flags_over_spec, print_json-from .pixel_gates import colors_used, evaluate, safe_area+from .pixel_gates import EFFECT, KINDS, SPRITE, TILE, colors_used, evaluate, safe_areafrom .pixel_grid import (FORMATS, PREVIEW_COLUMNS, Grid, Issue, PaletteRule, check_rows, frame_name_ok, frame_pixels, hold_palette,joined, palette_rule, parse_answer, parse_row_answers, png_bytes, preview_scale, preview_strip, read_grid_text,@@ -82,7 +82,6 @@ DRAWN_SHOWN = 4 # frames just before a later call's own that it is shown, withGRID_CHARS_PER_TOKEN = 2EFFECT_FRAMES_MAX = 8EFFECT_FRAMES = ("birth", "peak", "decay", "gone")-KINDS = ("sprite", "icon", "tile", "effect")CANDIDATES_MIN, CANDIDATES_MAX, CANDIDATES_DEFAULT = 1, 6, 2EFFORT_CHOICES = ("medium", "high", "xhigh")EFFORT_DEFAULT = "high"@@ -173,7 +172,7 @@ def _refuse(message: str) -> SystemExit:return SystemExit(f"{VERB}: {message}")-def _frames(value: Any, kind: str = "sprite") -> tuple[tuple[str, ...], dict[str, str]]:+def _frames(value: Any, kind: str = SPRITE) -> tuple[tuple[str, ...], dict[str, str]]:"""The frame names, and what each frame shows where a spec gave it (`{"name": ..., "pose": ...}`)."""items = [n.strip() for n in value.split(",")] if isinstance(value, str) else valueif not isinstance(items, list) or not items:@@ -193,9 +192,9 @@ def _frames(value: Any, kind: str = "sprite") -> tuple[tuple[str, ...], dict[strraise _refuse("frame names are letters, digits, '_' or '-' (at most 32): " + ", ".join(map(repr, bad)))if len(set(names)) != len(names):raise _refuse("frame names must differ: " + ", ".join(names))- if kind == "effect" and not 2 <= len(names) <= EFFECT_FRAMES_MAX:+ if kind == EFFECT and not 2 <= len(names) <= EFFECT_FRAMES_MAX:raise _refuse(f"an effect needs 2..{EFFECT_FRAMES_MAX} frames, got {len(names)}")- if kind != "effect" and len(names) > FRAMES_TOTAL_MAX:+ if kind != EFFECT and len(names) > FRAMES_TOTAL_MAX:raise _refuse(f"at most {FRAMES_TOTAL_MAX} frames, got {len(names)}")return tuple(names), poses@@ -215,7 +214,7 @@ def _words(value: Any, flag: str) -> str | None:def _motion(motion: str | None, kind: str, frames: tuple[str, ...]) -> None:- if motion is not None and kind == "effect":+ if motion is not None and kind == EFFECT:raise _refuse("--motion does not apply to an effect (its frames are a lifetime already)")if motion is not None and len(frames) < 2:raise _refuse(f"--motion is two or more frames in order, got {len(frames)}")@@ -246,16 +245,16 @@ def resolve_request(args: argparse.Namespace) -> PixelRequest:size = merged.get("size", SIZE_DEFAULT)if not isinstance(size, int) or isinstance(size, bool) or not SIZE_MIN <= size <= SIZE_MAX:raise _refuse(f"--size is {SIZE_MIN}..{SIZE_MAX} pixels, got {size!r}")- kind = merged.get("kind", "sprite")+ kind = merged.get("kind", SPRITE)if kind not in KINDS:raise _refuse(f"--kind is one of {', '.join(KINDS)}, got {kind!r}")frames, poses = _frames(merged["frames"], kind) if "frames" in merged else (- EFFECT_FRAMES if kind == "effect" else (kind,), {})+ EFFECT_FRAMES if kind == EFFECT else (kind,), {})style, motion = _words(merged.get("style"), "--style"), _words(merged.get("motion"), "--motion")_motion(motion, kind, frames)duration_ms = _duration(merged.get("duration_ms", GIF_FRAME_MS))walk_cycle = bool(merged.get("walk_cycle", False))- if walk_cycle and kind == "effect":+ if walk_cycle and kind == EFFECT:raise _refuse("--walk-cycle does not apply to an effect")if walk_cycle and len(frames) != 4:raise _refuse(f"--walk-cycle is four frames (contact, passing, contact, passing), got {len(frames)}")@@ -291,7 +290,7 @@ class Part:def call_parts(request: PixelRequest) -> list[Part]:"""The request's frames, FRAMES_MAX a call, in order. An effect is one call of its 2..8 frames."""frames = request.frames- if request.kind == "effect" or len(frames) <= FRAMES_MAX:+ if request.kind == EFFECT or len(frames) <= FRAMES_MAX:return [Part(1, 1, frames)]chunks = [frames[i:i + FRAMES_MAX] for i in range(0, len(frames), FRAMES_MAX)]return [Part(number, len(chunks), chunk) for number, chunk in enumerate(chunks, 1)]@@ -353,7 +352,7 @@ def safe_area_lines(request: PixelRequest) -> list[str]:size = request.sizearea = safe_area(size, size)margin, inner, floor = area["margin"][0], area["size"][0], area["floor_row"] + 1- sprite = request.kind == "sprite"+ sprite = request.kind == SPRITEif margin == 0:lines = [f"Safe area: at {size}x{size} there is no margin; {'the subject' if sprite else 'the icon'} may use ""the whole canvas, with the four corner pixels transparent."]@@ -389,7 +388,7 @@ def generation_prompt(request: PixelRequest, part: Part | None = None, drawn: Grframes = request.framesown = part.frames if part is not None else frameslines = [f"Draw: {request.subject}", f"Canvas: exactly {request.size}x{request.size} pixels per frame."]- if request.kind == "effect":+ if request.kind == EFFECT:lines.append(f"Frames: {', '.join(frames)}. One effect's lifetime: appears, grows to a peak, then disappears. ""Keep its origin fixed at the center of every frame. The final frame may be empty. ""Share a palette with several brightness levels for the glow; extent and shape change over time.")@@ -416,12 +415,12 @@ def generation_prompt(request: PixelRequest, part: Part | None = None, drawn: Gr+ " ".join(request.palette.colors) + ".")else:lines.append(f"Palette: at most {request.palette.limit} colors plus transparent.")- if request.kind == "tile":+ if request.kind == TILE:lines.append("This is a tile: fill every pixel (no transparency) and make it repeat seamlessly in a grid, ""so the left edge continues into the right edge and the top edge into the bottom edge. ""No border or outline around the tile.")lines.append(f"Style: {request.style or TILE_STYLE}")- elif request.kind == "effect":+ elif request.kind == EFFECT:lines.append("Background: transparent. Draw readable clusters of light; detached sparks are intentional. ""No dark outline, no ground plane, no antialiasing. Use the full canvas around its fixed center.")if request.style:@@ -495,7 +494,7 @@ def repair_prompt(request: PixelRequest, grid: Grid, issues: list[Issue]) -> tupdef _kept(request: PixelRequest) -> str:"""The safe area in the pick's words, so a margin the prompt asked for is not read as wasted canvas."""area = safe_area(request.size, request.size)- if request.kind in ("tile", "effect") or area["margin"][0] == 0:+ if request.kind in (TILE, EFFECT) or area["margin"][0] == 0:return ""inner = area["size"][0]return (f", the body about the size of the central {inner}x{inner}, inside a {area['margin'][0]}-pixel margin a "@@ -510,7 +509,7 @@ def pick_prompt(request: PixelRequest, labels: list[str]) -> str:"enlarged with nearest-neighbour scaling, so every square block is one pixel; the grey checkerboard stands ""for transparency.",]- if request.kind == "tile":+ if request.kind == TILE:lines.append("Each tile is shown alone and, to its right, repeated 3x3 so seams are visible.")if multi and len(request.frames) > PREVIEW_COLUMNS:lines.append(f"Each candidate's {len(request.frames)} frames run left to right in rows of {PREVIEW_COLUMNS}, top "@@ -526,9 +525,9 @@ def pick_prompt(request: PixelRequest, labels: list[str]) -> str:if request.style else"- craft 1-5: pixel-art craft: clean silhouette and outline, consistent shading and light, no noise, sensible ""use of the canvas (5 professional, 3 acceptable indie, 1 broken).")- + (" For tiles, visible seams in the 3x3 repeat count against craft." if request.kind == "tile" else ""),+ + (" For tiles, visible seams in the 3x3 repeat count against craft." if request.kind == TILE else ""),("- consistency 1-5: a readable lifetime around a fixed center, with a peak and decay; "- "changing extent, detached sparks and an empty final frame are intentional." if request.kind == "effect" else+ "changing extent, detached sparks and an empty final frame are intentional." if request.kind == EFFECT else"- consistency 1-5: the same subject, proportions and colours across frames, and the frames following one "f"another as one motion in their order ({request.motion})." if multi and request.motion else"- consistency 1-5: the same subject, proportions and colours across frames, and correct poses/directions "@@ -981,7 +980,7 @@ class Run:order = list(passed)random.Random(_sha(self.request.to_dict())).shuffle(order)by_label = {label: c for label, c in zip(labels, order)}- sheet = pick_sheet(self.run_dir, by_label, tile=self.request.kind == "tile",+ sheet = pick_sheet(self.run_dir, by_label, tile=self.request.kind == TILE,scale=preview_scale(self.request.size))sheet_path = self.run_dir / "pick-sheet.png"sheet_path.write_bytes(sheet)@@ -1094,13 +1093,13 @@ def write_files(directory: Path, grid: Grid, request_frames: tuple[str, ...], kifiles["frames"][name] = f"frame-{name}.png"preview_strip(list(frames.values()), scale).save(directory / f"preview-x{scale}.png")files["preview"] = f"preview-x{scale}.png"- if kind == "tile":+ if kind == TILE:tiled_3x3(frames[request_frames[0]], scale).save(directory / "tiled-3x3.png")files["tiled"] = "tiled-3x3.png"if len(frames) > 1:- save_gif(list(frames.values()), scale, directory / "anim.gif", duration_ms, loop=None if kind == "effect" else 0)+ save_gif(list(frames.values()), scale, directory / "anim.gif", duration_ms, loop=None if kind == EFFECT else 0)files["gif"] = "anim.gif"- if kind == "effect":+ if kind == EFFECT:strip = Image.new("RGBA", (grid.width * len(frames), grid.height))for i, pixels in enumerate(frames.values()):strip.paste(image_of(pixels), (i * grid.width, 0))@@ -1219,14 +1218,14 @@ def _run_grid(args: argparse.Namespace) -> int:rule = palette_rule(args.palette or "free")except ValueError as exc:raise _refuse(str(exc)) from exc- kind = args.kind or "sprite"+ kind = args.kind or SPRITEmotion = _words(args.motion, "--motion")duration_ms = _duration(GIF_FRAME_MS if args.duration_ms is None else args.duration_ms)grid, issues = read_grid_text(text)if grid is not None and not (SIZE_MIN <= grid.width <= SIZE_MAX and SIZE_MIN <= grid.height <= SIZE_MAX):raise _refuse(f"--grid {args.grid}: {grid.width}x{grid.height}; each side is {SIZE_MIN}..{SIZE_MAX} pixels")frames = tuple(grid.frames) if grid is not None else ()- if kind == "effect" and grid is not None:+ if kind == EFFECT and grid is not None:_frames(list(frames), kind)if args.walk_cycle:raise _refuse("--walk-cycle does not apply to an effect")diff --git a/sprite_gen/gen/pixel_gates.py b/sprite_gen/gen/pixel_gates.pyindex bab2089..3ef8d8b 100644--- a/sprite_gen/gen/pixel_gates.py+++ b/sprite_gen/gen/pixel_gates.py@@ -64,6 +64,9 @@ OPAQUE_MIN = 128 # the alpha at which a pixel is solid, as the engine reads solHEIGHT_SPREAD_MAX = 1WALK_CONTACT_RATIO_MIN = 0.4BODY_LINE_SHARE = 0.25+# What pixel-draw draws (`--kind`, `pixel_draw.KINDS`): a sprite or an icon on a transparent background, a tile+# that repeats, or an effect over frames of its own. The gates judge each kind by these names.+SPRITE, ICON, TILE, EFFECT = KINDS = ("sprite", "icon", "tile", "effect")Frame = Sequence[Sequence[Pixel]]@@ -103,9 +106,9 @@ def g3_alpha(frames: dict[str, Frame], kind: str) -> dict[str, Any]:from .chroma import RAW_ALPHA_NONE, RAW_ALPHA_REALper = {name: _frame_alpha(frame) for name, frame in frames.items()}- if kind == "tile":+ if kind == TILE:ok = all(m["verdict"] == RAW_ALPHA_NONE for m in per.values())- elif kind == "effect":+ elif kind == EFFECT:ok = (any(m["opaque_pixels"] > 0 for m in per.values())and all(m["corners_transparent"] and (m["opaque_pixels"] == 0 or m["verdict"] == RAW_ALPHA_REAL)for m in per.values()))@@ -265,7 +268,7 @@ def g8_safe_area(frames: dict[str, Frame], kind: str, area: dict[str, Any]) -> dfirst = frames[names[0]]mx, my = area["margin"]fit = safe_area_fit([tuple(per[name]["size"]) for name in names], len(first[0]), len(first), mx, my)- floor = area["floor_row"] if kind == "sprite" else None+ floor = area["floor_row"] if kind == SPRITE else Noneoff_floor = {name: m["body_box"][3] - floor for name, m in per.items()if floor is not None and m["body_box"] and m["body_box"][3] != floor}return {"warn": bool(fit["over"] or off_floor), "margin": area["margin"], "safe_area": fit["safe"],@@ -321,16 +324,16 @@ def evaluate(frames: dict[str, Frame], *, kind: str, rule: PaletteRule, walk_cycwarnings: list[str] = []info: list[str] = []first = next(iter(frames.values()))- area = None if kind in ("tile", "effect") else safe_area(len(first[0]), len(first))- if kind == "tile":+ area = None if kind in (TILE, EFFECT) else safe_area(len(first[0]), len(first))+ if kind == TILE:gates["G4"] = g4_seam(frames)if gates["G4"]["warn"]:warnings.append(_g4_line(gates["G4"]))- elif kind != "effect":+ elif kind != EFFECT:gates["G5"] = g5_isolated(frames)if gates["G5"]["warn"]:warnings.append(f"G5 {gates['G5']['isolated_pixels']} stray pixel(s) with no opaque neighbour")- if kind == "effect":+ if kind == EFFECT:gates["G6"] = {"ok": 2 <= len(frames) <= 8 and any(frame != first for frame in frames.values()),"rule": "2..8 frames with a visible change; extent, height and empty frames may differ"}elif len(frames) > 1: