Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

6.7 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""The safe-area judgment is one function, `frames.extract.safe_area_fit` (maintainer 2026-07-14): a
frame past the physical cap - the cell's width, its height less one margin - is a reroll candidate (a
warning); one past the safe area but within the cap is informational; nothing fails. The pixel snap of
`extract` and `pixel-draw`'s G8 both call it: what it answers is what both say, and the snap's two
lines read as they always have."""
from __future__ import annotations

import json
import random

import pytest
from PIL import Image

import sprite_gen.frames.extract as extract_module
from sprite_gen.frames.extract import safe_area_fit
from sprite_gen.gen import pixel_grid as pg
from sprite_gen.gen.pixel_gates import evaluate

MAGENTA = (255, 0, 255)
INK, CLEAR = (40, 30, 46, 255), (0, 0, 0, 0)


@pytest.mark.parametrize("size,over,soft", [
    ((26, 26), [], []),   # the safe area itself
    ((27, 26), [], [0]),  # a column past it
    ((26, 27), [], [0]),  # a row past it
    ((32, 29), [], [0]),  # the physical cap itself: the cell's width, its height less one margin
    ((32, 30), [0], []),  # a row past the cap
    ((33, 20), [0], []),  # wider than the cell
])
def test_the_tiers_of_a_32_px_cell(size, over, soft):
    assert safe_area_fit([size], 32, 32, 3, 3) == {"cap": [32, 29], "safe": [26, 26], "over": over, "soft": soft}


def test_the_tiers_count_logical_pixels_and_each_margin_on_its_own():
    """A 64 px cell at two cell pixels a logical pixel, margins 6 across and 4 down: cap 32x30, safe area 26x28."""
    fit = safe_area_fit([(26, 28), (27, 28), (26, 29), (32, 30), (32, 31)], 64, 64, 6, 4, scale=2)
    assert fit == {"cap": [32, 30], "safe": [26, 28], "over": [4], "soft": [1, 2, 3]}


def _logical_art(width: int, height: int, seed: int) -> Image.Image:
    rng = random.Random(seed)
    art = Image.new("RGB", (width, height), MAGENTA)
    for y in range(height):
        for x in range(width):
            if rng.random() < 0.55:
                art.putpixel((x, y), (rng.randrange(30, 220), rng.randrange(30, 220), rng.randrange(30, 220)))
    return art


def _snap_run(root, cell: int, margin: int):
    """Two frames of 20x36 logical pixels drawn at a pitch of 8, snapped 1:1 into a `cell` px cell."""
    run_dir = root / "run"
    (run_dir / "raw").mkdir(parents=True)
    pitch, gap = 8, 40
    frame = _logical_art(20, 36, seed=7).resize((20 * pitch, 36 * pitch), Image.Resampling.NEAREST)
    strip = Image.new("RGB", (frame.width * 2 + gap * 3, frame.height + gap * 2), MAGENTA)
    strip.paste(frame, (gap, gap))
    strip.paste(frame, (frame.width + gap * 2, gap))
    strip.save(run_dir / "raw" / "walk.png")
    request = {
        "version": 1,
        "kind": "sprite-gen-request",
        "engine": "component-row",
        "character": {"id": "safebot", "description": "safe area fixture", "base_image": None},
        "cell": {"shape": "square", "width": cell, "height": cell, "safe_margin_x": margin, "safe_margin_y": margin,
                 "size": cell, "safe_margin": margin},
        "chroma_key": {"name": "magenta", "hex": "#FF00FF", "rgb": [255, 0, 255], "selection": "fallback"},
        "states": {"walk": {"frames": 2, "fps": 8, "loop": True, "action": "synthetic safe area fixture"}},
        "fit": {"pixel_unfake": True},
    }
    (run_dir / "sprite-request.json").write_text(json.dumps(request, indent=2) + "\n", encoding="utf-8")
    return run_dir


def _warnings(run_dir) -> list[str]:
    return json.loads((run_dir / "frames" / "frames-manifest.json").read_text(encoding="utf-8"))["warnings"]


@pytest.fixture
def calls(monkeypatch):
    """Every call to the judgment, with what it answered."""
    real, seen = extract_module.safe_area_fit, []

    def recording(*args, **kwargs):
        seen.append((args, kwargs, real(*args, **kwargs)))
        return seen[-1][2]

    monkeypatch.setattr(extract_module, "safe_area_fit", recording)
    return seen


def test_the_snap_notes_a_frame_past_the_safe_area_in_its_own_words(tmp_path, calls):
    run_dir = _snap_run(tmp_path, 48, 8)  # safe area 32x32, cap 48x40: 36 rows are past one, within the other
    assert extract_module.run(run_dir=run_dir) == 0
    ((args, kwargs, fit),) = calls
    assert args == ([(20, 36), (20, 36)], 48, 48, 8, 8, 1) and kwargs == {}
    assert fit == {"cap": [48, 40], "safe": [32, 32], "over": [], "soft": [0, 1]}
    warnings = _warnings(run_dir)
    assert ("walk: frames exceed the safe area 32x32 but fit within the margin zone (informational, no action): "
            "0:20x36, 1:20x36") in warnings
    assert not any("physical cap" in line for line in warnings)


def test_the_snap_warns_a_frame_past_the_physical_cap_in_its_own_words(tmp_path, calls):
    run_dir = _snap_run(tmp_path, 40, 6)  # cap 40x34: 36 rows are past it
    assert extract_module.run(run_dir=run_dir) == 0
    ((args, _, fit),) = calls
    assert args[1:] == (40, 40, 6, 6, 1) and fit["over"] == [0, 1] and fit["soft"] == []
    warnings = _warnings(run_dir)
    assert ("walk: native logical exceeds the physical cap 40x34 — capped frames (reroll candidates): "
            "0:20x36, 1:20x36") in warnings
    assert not any("margin zone" in line for line in warnings)


def test_pixel_draw_asks_it_with_the_canvas_and_the_engines_margin(calls):
    frame = [[INK if 3 <= y <= 28 and 8 <= x <= 23 else CLEAR for x in range(32)] for y in range(32)]
    gates = evaluate({"f": frame}, kind="sprite", rule=pg.palette_rule("free"), walk_cycle=False)
    ((args, kwargs, fit),) = calls
    assert args == ([(16, 26)], 32, 32, 3, 3) and kwargs == {}
    assert gates["G8"]["physical_cap"] == fit["cap"] and gates["G8"]["safe_area"] == fit["safe"]


def test_both_paths_say_what_it_answers(tmp_path, monkeypatch):
    """Answer that every frame is past the safe area: the snap and G8 both say so of frames well inside it."""
    real = extract_module.safe_area_fit

    def past(sizes, *args, **kwargs):
        return {**real(sizes, *args, **kwargs), "over": [], "soft": list(range(len(sizes)))}

    monkeypatch.setattr(extract_module, "safe_area_fit", past)
    small = [[INK if 19 <= y <= 28 and 11 <= x <= 20 else CLEAR for x in range(32)] for y in range(32)]
    gates = evaluate({"f": small}, kind="sprite", rule=pg.palette_rule("free"), walk_cycle=False)
    assert gates["ok"] and gates["warnings"] == []
    assert gates["info"] == ["G8: frames exceed the safe area 26x26 but fit within the margin zone (informational, "
                             "no action): f:10x10"]
    run_dir = _snap_run(tmp_path, 96, 8)  # safe area 80x80
    assert extract_module.run(run_dir=run_dir) == 0
    assert ("walk: frames exceed the safe area 80x80 but fit within the margin zone (informational, no action): "
            "0:20x36, 1:20x36") in _warnings(run_dir)