spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/sprites/importer.py

@@ -0,0 +1,212 @@
+"""Import existing art into a SpriteSet: grid sheets, auto-sliced sheets, or folders of frames."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from .spriteset import ANIM_ORDER, SpriteError, SpriteSet, build_sheet, finalize
+
+DEFAULT_FPS = {"idle": 4.0, "run": 10.0, "jump": 8.0, "fall": 8.0, "hurt": 8.0}
+ANIM_SYNONYMS = {
+    "idle": "idle", "stand": "idle", "rest": "idle", "breath": "idle",
+    "run": "run", "walk": "run", "move": "run",
+    "jump": "jump", "up": "jump", "fall": "fall", "down": "fall",
+    "hurt": "hurt", "hit": "hurt", "damage": "hurt", "pain": "hurt",
+}
+
+
+def parse_ranges(spec: str) -> list[int]:
+    """'0-3,7,9-10' -> [0, 1, 2, 3, 7, 9, 10]."""
+    out: list[int] = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            a, b = part.split("-", 1)
+            out.extend(range(int(a), int(b) + 1))
+        else:
+            out.append(int(part))
+    return out
+
+
+def _runs(occupied: np.ndarray) -> list[tuple[int, int]]:
+    """[start, end) runs of True values."""
+    runs, start = [], None
+    for i, v in enumerate(occupied):
+        if v and start is None:
+            start = i
+        elif not v and start is not None:
+            runs.append((start, i))
+            start = None
+    if start is not None:
+        runs.append((start, len(occupied)))
+    return runs
+
+
+def _pad_to(frame: np.ndarray, w: int, h: int, anchor: str) -> np.ndarray:
+    out = np.zeros((h, w, 4), dtype=np.uint8)
+    fh, fw = frame.shape[:2]
+    x = (w - fw) // 2
+    y = h - fh if anchor == "bottom" else (h - fh) // 2
+    out[y:y + fh, x:x + fw] = frame
+    return out
+
+
+def _trim(frame: np.ndarray) -> np.ndarray:
+    ys, xs = np.nonzero(frame[..., 3] > 0)
+    if len(xs) == 0:
+        return frame[:1, :1]
+    return frame[ys.min():ys.max() + 1, xs.min():xs.max() + 1]
+
+
+def slice_grid(img: np.ndarray, cell: tuple[int, int], spacing: int = 0, margin: int = 0) -> list[list[np.ndarray]]:
+    """Rows of cells (empty cells included, so indices match what the artist sees)."""
+    cw, ch = cell
+    h, w = img.shape[:2]
+    rows = []
+    y = margin
+    while y + ch <= h:
+        row = []
+        x = margin
+        while x + cw <= w:
+            row.append(img[y:y + ch, x:x + cw])
+            x += cw + spacing
+        rows.append(row)
+        y += ch + spacing
+    if not rows or not rows[0]:
+        raise SpriteError(f"a {cw}x{ch} grid does not fit a {w}x{h} sheet")
+    return rows
+
+
+def slice_auto(img: np.ndarray) -> list[list[np.ndarray]]:
+    """Frames separated by fully transparent gutters. Returns rows of trimmed frames."""
+    alpha = img[..., 3] > 0
+    row_runs = _runs(alpha.any(axis=1))
+    if not row_runs:
+        raise SpriteError("the image is fully transparent")
+    rows = []
+    for y0, y1 in row_runs:
+        band = img[y0:y1]
+        cols = _runs((band[..., 3] > 0).any(axis=0))
+        rows.append([_trim(band[:, x0:x1]) for x0, x1 in cols])
+    return rows
+
+
+def _empty(frame: np.ndarray) -> bool:
+    return not (frame[..., 3] > 0).any()
+
+
+def from_rows(name: str, rows: list[list[np.ndarray]], *, anims: dict[str, list[int]] | None = None,
+              row_names: list[str] | None = None, fps: dict[str, float] | None = None, scale: int = 2,
+              anchor: str = "bottom", trim: bool = False) -> SpriteSet:
+    fps = {**DEFAULT_FPS, **(fps or {})}
+    flat = [f for row in rows for f in row]
+    if anims:
+        chosen = {}
+        for anim, idx in anims.items():
+            bad = [i for i in idx if not 0 <= i < len(flat)]
+            if bad:
+                raise SpriteError(f"animation '{anim}' uses frame {bad[0]}, but the sheet has {len(flat)} frames (0-{len(flat) - 1})")
+            empty = [i for i in idx if _empty(flat[i])]
+            if empty:
+                raise SpriteError(f"animation '{anim}' uses empty frame(s) {empty}; non-empty frames are "
+                                  f"{[i for i, f in enumerate(flat) if not _empty(f)]}")
+            chosen[anim] = [flat[i] for i in idx]
+    else:
+        nonempty_rows = [[f for f in row if not _empty(f)] for row in rows]
+        nonempty_rows = [r for r in nonempty_rows if r]
+        if not nonempty_rows:
+            raise SpriteError("no non-empty frames found")
+        if row_names:
+            if len(row_names) > len(nonempty_rows):
+                raise SpriteError(f"{len(row_names)} row names given but the sheet has {len(nonempty_rows)} rows")
+            chosen = {n: nonempty_rows[i] for i, n in enumerate(row_names)}
+        elif len(nonempty_rows) > 1:
+            chosen = {(ANIM_ORDER[i] if i < len(ANIM_ORDER) else f"row{i}"): r for i, r in enumerate(nonempty_rows)}
+        else:
+            chosen = {"idle": nonempty_rows[0]}
+    if trim:
+        chosen = {k: [_trim(f) for f in v] for k, v in chosen.items()}
+    w = max(f.shape[1] for fs in chosen.values() for f in fs)
+    h = max(f.shape[0] for fs in chosen.values() for f in fs)
+    frames = {k: [_pad_to(f, w, h, anchor) for f in v] for k, v in chosen.items()}
+    sheet, animations = build_sheet(frames, {k: fps.get(k, 8.0) for k in frames}, {k: k not in ("jump", "fall", "hurt") for k in frames})
+    return finalize(name, sheet, (w, h), animations, scale, anchor)
+
+
+def import_sheet(path: Path, name: str | None = None, *, grid: tuple[int, int] | None = None, spacing: int = 0,
+                 margin: int = 0, anims: dict[str, list[int]] | None = None, row_names: list[str] | None = None,
+                 fps: dict[str, float] | None = None, scale: int = 2, anchor: str = "bottom") -> SpriteSet:
+    img = np.asarray(Image.open(path).convert("RGBA"))
+    name = name or _clean_name(Path(path).stem)
+    if grid:
+        rows = slice_grid(img, grid, spacing, margin)
+        return from_rows(name, rows, anims=anims, row_names=row_names, fps=fps, scale=scale, anchor=anchor)
+    rows = slice_auto(img)
+    return from_rows(name, rows, anims=anims, row_names=row_names, fps=fps, scale=scale, anchor=anchor)
+
+
+_FRAME_FILE = re.compile(r"^(?P<stem>.*?)[\s_\-.]*(?P<num>\d+)$")
+
+
+def import_folder(directory: Path, name: str | None = None, *, fps: dict[str, float] | None = None,
+                  scale: int = 2, anchor: str = "bottom") -> SpriteSet:
+    """Frames named like idle_0.png, hero-walk-03.png, run1.png; files without a number are idle."""
+    files = sorted(p for p in Path(directory).iterdir() if p.suffix.lower() == ".png")
+    if not files:
+        raise SpriteError(f"no PNG files in {directory}")
+    groups: dict[str, list[tuple[int, np.ndarray]]] = {}
+    for p in files:
+        m = _FRAME_FILE.match(p.stem)
+        stem, num = (m.group("stem"), int(m.group("num"))) if m else (p.stem, 0)
+        anim = _anim_name(stem)
+        groups.setdefault(anim, []).append((num, np.asarray(Image.open(p).convert("RGBA"))))
+    rows_by_anim = {k: [f for _, f in sorted(v, key=lambda t: t[0])] for k, v in groups.items()}
+    if "idle" not in rows_by_anim:
+        first = next(iter(rows_by_anim))
+        rows_by_anim["idle"] = rows_by_anim.pop(first)
+    names = list(rows_by_anim)
+    return from_rows(name or _clean_name(Path(directory).name), [rows_by_anim[n] for n in names],
+                     row_names=names, fps=fps, scale=scale, anchor=anchor, trim=True)
+
+
+def _anim_name(stem: str) -> str:
+    tokens = [t.lower() for t in re.split(r"[\s_\-.]+", stem) if t]
+    for t in reversed(tokens):
+        if t in ANIM_SYNONYMS:
+            return ANIM_SYNONYMS[t]
+    return tokens[-1] if tokens else "idle"
+
+
+def _clean_name(raw: str) -> str:
+    words = re.findall(r"[A-Za-z0-9]+", raw)
+    return "".join(w[:1].upper() + w[1:] for w in words) or "Sprite"
+
+
+def preview(s: SpriteSet, zoom: int = 6, show_polygon: bool = True) -> Image.Image:
+    """Contact sheet: one row per animation, plus the collision outline on the first idle frame."""
+    from PIL import ImageDraw
+
+    w, h = s.frame_size
+    cols = max(len(a.frames) for a in s.animations.values())
+    out = Image.new("RGBA", ((cols + 1) * (w * zoom + 8) + 120, len(s.animations) * (h * zoom + 8) + 8), (40, 44, 60, 255))
+    d = ImageDraw.Draw(out)
+    for r, (anim, a) in enumerate(s.animations.items()):
+        y = 4 + r * (h * zoom + 8)
+        d.text((4, y + 4), f"{anim} ({len(a.frames)}f @{a.fps:g})", fill=(255, 241, 232, 255))
+        for c, (col, row) in enumerate(a.frames):
+            f = Image.fromarray(s.frame(col, row)).resize((w * zoom, h * zoom), Image.NEAREST)
+            out.alpha_composite(f, (120 + c * (w * zoom + 8), y))
+    if show_polygon and s.polygon:
+        idle = s.animations.get("idle") or next(iter(s.animations.values()))
+        x0 = 120 + cols * (w * zoom + 8)
+        f = Image.fromarray(s.frame(*idle.frames[0])).resize((w * zoom, h * zoom), Image.NEAREST)
+        out.alpha_composite(f, (x0, 4))
+        pts = [(x0 + px * zoom, 4 + py * zoom) for px, py in s.polygon]
+        d.line(pts + pts[:1], fill=(0, 228, 54, 255), width=2)
+    return out

spawnpoint/sprites/resolve.py

@@ -0,0 +1,139 @@
+"""Connects sprites to the compiler: resolve an entity's sprite, derive its collision, plan entries."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..graph import Entity, Shape
+from .generate import KINDS, generate
+from .spriteset import SpriteError, SpriteSet, load
+
+SPRITE_DIR = "res://sprites"
+
+
+def resolve(name: str, ent: Entity, base_dir: Path | None, default_color: str,
+            warn=lambda msg: None) -> SpriteSet:
+    """`warn(message)` reports a non-fatal problem (an AI sprite falling back to a generated one)."""
+    ref = ent.sprite
+    if isinstance(ref, str):
+        path = Path(ref)
+        if not path.is_absolute():
+            if base_dir is None:
+                raise SpriteError(f"relative sprite path '{ref}' needs the graph's folder (build from a file)")
+            path = base_dir / path
+        if not path.exists():
+            raise SpriteError(f"sprite file '{ref}' not found")
+        return load(path)
+    if ref.ai is not None:
+        from .ai import ai_sprite, provider_from_env
+
+        spec = ref.ai
+        if spec.kind not in KINDS:
+            raise SpriteError(f"unknown sprite kind '{spec.kind}'")
+        provider = provider_from_env()
+        if provider is None:
+            warn("no image provider configured (SPAWNPOINT_IMAGE_PROVIDER); using a generated sprite")
+        else:
+            try:
+                return ai_sprite(name, spec.kind, spec.prompt, provider, spec.seed)
+            except SpriteError as e:
+                warn(f"AI sprite failed ({e}); using a generated sprite")
+        return generate(name, spec.kind, spec.color or default_color, None, spec.seed)
+    gen = ref.generate
+    if gen.kind not in KINDS:
+        raise SpriteError(f"unknown sprite kind '{gen.kind}'")
+    return generate(name, gen.kind, gen.color or default_color, gen.features, gen.seed)
+
+
+def derived_shape(ent: Entity, s: SpriteSet, genre: str) -> Shape:
+    """Body collision fitted to the sprite's opaque bounds (smooth shapes for moving bodies)."""
+    _, _, bw, bh = s.bounds
+    w, h = bw * s.scale, bh * s.scale
+    color = ent.shape.color
+    if ent.body == "character":
+        if genre == "topdown":
+            d = min(w, h) * 0.9
+            return Shape(type="circle", size=(d, d), color=color)
+        return Shape(type="capsule", size=(max(w * 0.8, 4), h), color=color)
+    return Shape(type="rect", size=(w, h), color=color)
+
+
+def plan_entry(entity: str, s: SpriteSet) -> dict:
+    fw, fh = s.frame_size
+    bx, by, bw, bh = s.bounds
+    cx, cy = bx + bw / 2, by + bh / 2  # the entity origin sits at the center of the opaque box
+    k = s.scale
+    return {
+        "texture": f"{SPRITE_DIR}/{entity}.png",
+        "frame_size": [fw, fh],
+        "scale": k,
+        "offset": [round((fw / 2 - cx) * k, 3), round((fh / 2 - cy) * k, 3)],
+        "animations": {n: {"frames": [list(f) for f in a.frames], "fps": a.fps, "loop": a.loop}
+                       for n, a in s.animations.items()},
+        "polygon": [[round((x - cx) * k, 2), round((y - cy) * k, 2)] for x, y in safe_polygon(s.polygon)],
+        "color": s.color,
+    }
+
+
+def safe_polygon(poly: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    """A simple (non self-intersecting) polygon Godot can decompose; falls back to the convex hull."""
+    if len(poly) >= 3 and _is_simple(poly) and abs(_area(poly)) > 0.5:
+        return poly
+    return convex_hull(poly)
+
+
+def convex_hull(pts: list[tuple[float, float]]) -> list[tuple[float, float]]:
+    p = sorted(set(pts))
+    if len(p) < 3:
+        return p
+
+    def cross(o, a, b):
+        return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+    lower: list = []
+    for q in p:
+        while len(lower) >= 2 and cross(lower[-2], lower[-1], q) <= 0:
+            lower.pop()
+        lower.append(q)
+    upper: list = []
+    for q in reversed(p):
+        while len(upper) >= 2 and cross(upper[-2], upper[-1], q) <= 0:
+            upper.pop()
+        upper.append(q)
+    return lower[:-1] + upper[:-1]
+
+
+def _area(pts) -> float:
+    return sum(x1 * y2 - x2 * y1 for (x1, y1), (x2, y2) in zip(pts, pts[1:] + pts[:1])) / 2
+
+
+def _is_simple(pts: list[tuple[float, float]]) -> bool:
+    n = len(pts)
+    if len(set(pts)) != n:
+        return False
+    segs = [(pts[i], pts[(i + 1) % n]) for i in range(n)]
+    for i in range(n):
+        for j in range(i + 1, n):
+            if j == i + 1 or (i == 0 and j == n - 1):
+                continue
+            if _intersect(*segs[i], *segs[j]):
+                return False
+    return True
+
+
+def _intersect(a, b, c, d) -> bool:
+    def orient(p, q, r):
+        v = (q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0])
+        return 0 if abs(v) < 1e-9 else (1 if v > 0 else -1)
+
+    o1, o2, o3, o4 = orient(a, b, c), orient(a, b, d), orient(c, d, a), orient(c, d, b)
+    if o1 != o2 and o3 != o4:
+        return True
+
+    def on(p, q, r):
+        return min(p[0], r[0]) <= q[0] <= max(p[0], r[0]) and min(p[1], r[1]) <= q[1] <= max(p[1], r[1])
+
+    return (o1 == 0 and on(a, c, b)) or (o2 == 0 and on(a, d, b)) or (o3 == 0 and on(c, a, d)) or (o4 == 0 and on(c, b, d))
+
+
+__all__ = ["resolve", "derived_shape", "plan_entry", "safe_polygon", "SpriteError", "SPRITE_DIR"]

spawnpoint/sprites/spriteset.py

@@ -0,0 +1,159 @@
+"""SpriteSet: a uniform-grid sprite sheet + animations + bounds/outline, shared by generator and importer."""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+from . import contour
+
+FORMAT = 1
+ANIM_ORDER = ("idle", "run", "jump", "fall", "hurt")
+
+
+class SpriteError(ValueError):
+    pass
+
+
+@dataclass
+class Animation:
+    frames: list[tuple[int, int]]  # (column, row) grid cells
+    fps: float = 8.0
+    loop: bool = True
+
+    def to_dict(self) -> dict:
+        return {"frames": [list(f) for f in self.frames], "fps": self.fps, "loop": self.loop}
+
+
+@dataclass
+class SpriteSet:
+    name: str
+    sheet: Image.Image
+    frame_size: tuple[int, int]
+    animations: dict[str, Animation]
+    scale: int = 2
+    anchor: str = "center"  # center | bottom
+    bounds: tuple[int, int, int, int] = (0, 0, 0, 0)  # opaque box of the idle pose, frame pixels
+    polygon: list[tuple[float, float]] = field(default_factory=list)  # outline of the idle pose
+    color: str = "#ffffff"
+
+    @property
+    def columns(self) -> int:
+        return self.sheet.width // self.frame_size[0]
+
+    @property
+    def rows(self) -> int:
+        return self.sheet.height // self.frame_size[1]
+
+    def frame(self, col: int, row: int) -> np.ndarray:
+        w, h = self.frame_size
+        return np.asarray(self.sheet.crop((col * w, row * h, col * w + w, row * h + h)).convert("RGBA"))
+
+    def to_dict(self, image_name: str) -> dict:
+        return {
+            "format": FORMAT, "name": self.name, "image": image_name, "frame_size": list(self.frame_size),
+            "scale": self.scale, "anchor": self.anchor,
+            "animations": {k: a.to_dict() for k, a in self.animations.items()},
+            "bounds": list(self.bounds), "polygon": [list(p) for p in self.polygon], "color": self.color,
+        }
+
+    def save(self, directory: Path, name: str | None = None) -> Path:
+        directory.mkdir(parents=True, exist_ok=True)
+        base = name or self.name
+        self.sheet.save(directory / f"{base}.png")
+        path = directory / f"{base}.sprite.json"
+        path.write_text(json.dumps(self.to_dict(f"{base}.png"), indent=1) + "\n")
+        return path
+
+
+def finalize(name: str, sheet: Image.Image, frame_size: tuple[int, int], animations: dict[str, Animation],
+             scale: int = 2, anchor: str = "center") -> SpriteSet:
+    """Validates the grid and derives bounds, outline and dominant color from the idle pose."""
+    sheet = sheet.convert("RGBA")
+    s = SpriteSet(name, sheet, tuple(frame_size), dict(animations), scale, anchor)
+    _check(s)
+    idle = s.animations.get("idle") or next(iter(s.animations.values()))
+    union = np.zeros((frame_size[1], frame_size[0], 4), dtype=np.uint8)
+    for col, row in idle.frames:
+        f = s.frame(col, row)
+        union = np.where(f[..., 3:4] > union[..., 3:4], f, union)
+    mask = contour.alpha_mask(union)
+    b = contour.bounds(mask)
+    if b is None:
+        raise SpriteError(f"sprite '{name}': the idle frames are fully transparent")
+    s.bounds = b
+    s.polygon = contour.outline(union)
+    s.color = dominant_color(union)
+    return s
+
+
+def _check(s: SpriteSet) -> None:
+    w, h = s.frame_size
+    if w <= 0 or h <= 0:
+        raise SpriteError(f"sprite '{s.name}': bad frame size {w}x{h}")
+    if s.sheet.width % w or s.sheet.height % h:
+        raise SpriteError(f"sprite '{s.name}': sheet {s.sheet.width}x{s.sheet.height} is not a multiple of {w}x{h}")
+    if not s.animations:
+        raise SpriteError(f"sprite '{s.name}': no animations")
+    for anim_name, a in s.animations.items():
+        if not a.frames:
+            raise SpriteError(f"sprite '{s.name}': animation '{anim_name}' has no frames")
+        for col, row in a.frames:
+            if not (0 <= col < s.columns and 0 <= row < s.rows):
+                raise SpriteError(f"sprite '{s.name}': animation '{anim_name}' uses frame ({col},{row}) "
+                                  f"outside the {s.columns}x{s.rows} grid")
+
+
+def dominant_color(rgba: np.ndarray) -> str:
+    px = rgba[rgba[..., 3] >= 128][:, :3]
+    if len(px) == 0:
+        return "#ffffff"
+    # Ignore near-black outline pixels, quantize, take the most common.
+    lum = px.astype(int).sum(axis=1)
+    px = px[lum > 120] if (lum > 120).any() else px
+    q = (px // 16) * 16 + 8
+    (r, g, b), _ = Counter(map(tuple, q.tolist())).most_common(1)[0]
+    return f"#{int(r):02x}{int(g):02x}{int(b):02x}"
+
+
+def load(path: Path) -> SpriteSet:
+    path = Path(path)
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as e:
+        raise SpriteError(f"cannot read sprite file {path}: {e}") from e
+    try:
+        image = Image.open(path.parent / data["image"]).convert("RGBA")
+        anims = {k: Animation([tuple(f) for f in v["frames"]], float(v.get("fps", 8)), bool(v.get("loop", True)))
+                 for k, v in data["animations"].items()}
+        s = SpriteSet(data.get("name", path.stem), image, tuple(data["frame_size"]), anims,
+                      int(data.get("scale", 2)), data.get("anchor", "center"))
+    except (KeyError, OSError, TypeError, ValueError) as e:
+        raise SpriteError(f"invalid sprite file {path}: {e}") from e
+    _check(s)
+    if data.get("bounds") and data.get("polygon"):
+        s.bounds = tuple(data["bounds"])
+        s.polygon = [tuple(p) for p in data["polygon"]]
+        s.color = data.get("color", "#ffffff")
+        return s
+    return finalize(s.name, s.sheet, s.frame_size, s.animations, s.scale, s.anchor)
+
+
+def build_sheet(frames: dict[str, list[np.ndarray]], fps: dict[str, float], loop: dict[str, bool]
+                ) -> tuple[Image.Image, dict[str, Animation]]:
+    """Lays out frames row-per-animation in ANIM_ORDER (then any others)."""
+    names = [n for n in ANIM_ORDER if n in frames] + [n for n in frames if n not in ANIM_ORDER]
+    h, w = next(iter(frames.values()))[0].shape[:2]
+    cols = max(len(frames[n]) for n in names)
+    sheet = np.zeros((h * len(names), w * cols, 4), dtype=np.uint8)
+    anims = {}
+    for row, n in enumerate(names):
+        for col, f in enumerate(frames[n]):
+            sheet[row * h:(row + 1) * h, col * w:(col + 1) * w] = f
+        anims[n] = Animation([(c, row) for c in range(len(frames[n]))], fps.get(n, 8.0), loop.get(n, True))
+    return Image.fromarray(sheet, "RGBA"), anims

spawnpoint/sprites/tiles.py

@@ -0,0 +1,102 @@
+"""Pixel-art tile atlas: [solid with exposed top, solid inner, one-way] in one row.
+
+Drawn on a half-resolution grid and scaled 2x (same look as the sprites). Platformers get dirt with
+a grassy top and wooden planks; top-down games get stone-brick walls with a lit top edge.
+"""
+
+from __future__ import annotations
+
+import random
+
+import numpy as np
+from PIL import Image
+
+from .generate import _hex, _rgba, ramp
+
+TILES = ("solid_top", "solid", "oneway")
+
+
+def _shade(color: str, k: float) -> tuple:
+    r, g, b = _hex(color)
+    return _rgba(r * k, g * k, b * k)
+
+
+def tileset(genre: str, solid: str, top: str, oneway: str, tile_size: int = 32, seed: int = 0) -> Image.Image:
+    n = max(tile_size // 2, 4)
+    canvas = np.zeros((n, n * 3, 4), dtype=np.uint8)
+    rng = random.Random(f"tiles:{seed}")
+    if genre == "topdown":
+        _bricks(canvas[:, 0:n], solid, top, rng, lit_top=True)
+        _bricks(canvas[:, n:2 * n], solid, top, rng, lit_top=False)
+    else:
+        _dirt(canvas[:, n:2 * n], solid, rng)
+        _dirt(canvas[:, 0:n], solid, rng)
+        _grass(canvas[:, 0:n], top, rng)
+    _plank(canvas[:, 2 * n:3 * n], oneway, rng)
+    img = Image.fromarray(canvas, "RGBA")
+    return img.resize((tile_size * 3, tile_size), Image.NEAREST)
+
+
+def _dirt(px: np.ndarray, color: str, rng: random.Random) -> None:
+    n = px.shape[0]
+    r = ramp(color)
+    px[:, :] = r.base
+    for _ in range(n * n // 10):  # pebbles and specks
+        x, y = rng.randrange(n), rng.randrange(n)
+        px[y, x] = r.shadow if rng.random() < 0.7 else r.light
+        if rng.random() < 0.3 and x + 1 < n:
+            px[y, x + 1] = r.shadow
+    px[n - 1, :] = _shade(color, 0.6)  # seam between tiles reads as depth
+    px[:, n - 1] = _shade(color, 0.7)
+
+
+def _grass(px: np.ndarray, color: str, rng: random.Random) -> None:
+    n = px.shape[0]
+    r = ramp(color)
+    depth = max(2, n // 4)
+    for x in range(n):
+        d = depth + (1 if rng.random() < 0.45 else 0)
+        px[0:d, x] = r.base
+        px[0, x] = r.light
+        px[d, x] = r.shadow  # drop shadow under the turf
+        if rng.random() < 0.25:
+            px[d + 1 if d + 1 < n else d, x] = r.shadow
+    for _ in range(n // 3):  # a few bright blades
+        px[rng.randrange(1, depth), rng.randrange(n)] = r.light
+
+
+def _bricks(px: np.ndarray, color: str, cap: str, rng: random.Random, lit_top: bool) -> None:
+    n = px.shape[0]
+    r = ramp(color)
+    mortar = _shade(color, 0.55)
+    px[:, :] = r.base
+    row_h = max(3, n // 4)
+    for row, y0 in enumerate(range(0, n, row_h)):
+        px[y0, :] = mortar
+        offset = (n // 4) if row % 2 else 0
+        for x in range(offset, n + offset, max(4, n // 2)):
+            px[y0:y0 + row_h, x % n] = mortar
+        for x in range(n):  # light the top row of each brick
+            if y0 + 1 < n and px[y0 + 1, x].tolist() != list(mortar):
+                px[y0 + 1, x] = r.light
+    for _ in range(n * n // 16):
+        x, y = rng.randrange(n), rng.randrange(n)
+        if px[y, x].tolist() == list(r.base):
+            px[y, x] = r.shadow
+    if lit_top:
+        c = ramp(cap)
+        px[0:2, :] = c.base
+        px[0, :] = c.light
+
+
+def _plank(px: np.ndarray, color: str, rng: random.Random) -> None:
+    n = px.shape[0]
+    r = ramp(color)
+    h = max(3, int(n * 0.3))
+    px[0:h, :] = r.base
+    px[0, :] = r.light
+    px[h - 1, :] = r.shadow
+    for x in range(0, n, max(3, n // 3)):  # grain and joints
+        px[1:h - 1, x] = r.shadow
+    for x in (1, n - 2):
+        px[h // 2, x] = (230, 220, 200, 255)  # nails