Procedural Generation skill for Claude Code

#!/usr/bin/env python3
"""Seeded dungeon/cave generator and reproducibility checker (stdlib only).

Generates a tile map with BSP rooms+corridors or cellular-automata caves, validates it
(connectivity, open-area ratio, room count), prints it as ASCII, and prints a hash of
the map so the same seed can be compared across machines, languages, or commits.

  python3 dungeon_gen.py --algo bsp --seed 42 --width 60 --height 30
  python3 dungeon_gen.py --algo caves --seed 7 --width 80 --height 40 --quiet
  python3 dungeon_gen.py --algo bsp --seed 42 --expect-hash 3f2a...   # regression check
  python3 dungeon_gen.py --algo bsp --sweep 500                       # validate 500 seeds

Exit status: 0 = valid (and hash matched if given), 1 = validation or hash failure,
2 = bad arguments.
"""
from __future__ import annotations

import argparse
import hashlib
import random
import sys
from collections import deque

WALL, FLOOR = "#", "."


def new_grid(w: int, h: int) -> list[list[str]]:
    return [[WALL] * w for _ in range(h)]


# ---------- BSP rooms and corridors ----------
def bsp(w: int, h: int, rng: random.Random, min_leaf: int = 8) -> tuple[list[list[str]], int]:
    grid = new_grid(w, h)
    leaves = [(1, 1, w - 2, h - 2)]  # x, y, width, height (inside the outer wall)
    changed = True
    while changed:
        changed = False
        nxt = []
        for (x, y, lw, lh) in leaves:
            can_h = lh >= 2 * min_leaf
            can_v = lw >= 2 * min_leaf
            if not (can_h or can_v) or (lw < 3 * min_leaf and lh < 3 * min_leaf and rng.random() < 0.25):
                nxt.append((x, y, lw, lh))
                continue
            # split across the longer side to avoid long thin leaves
            horizontal = can_h and (not can_v or lh > lw or (lh == lw and rng.random() < 0.5))
            if horizontal:
                cut = rng.randint(min_leaf, lh - min_leaf)
                nxt += [(x, y, lw, cut), (x, y + cut, lw, lh - cut)]
            else:
                cut = rng.randint(min_leaf, lw - min_leaf)
                nxt += [(x, y, cut, lh), (x + cut, y, lw - cut, lh)]
            changed = True
        leaves = nxt

    centers = []
    for (x, y, lw, lh) in leaves:  # one room per leaf, with a 1-tile margin
        rw = rng.randint(max(3, lw // 2), lw - 2)
        rh = rng.randint(max(3, lh // 2), lh - 2)
        rx = rng.randint(x + 1, x + lw - rw - 1)
        ry = rng.randint(y + 1, y + lh - rh - 1)
        for yy in range(ry, ry + rh):
            for xx in range(rx, rx + rw):
                grid[yy][xx] = FLOOR
        centers.append((rx + rw // 2, ry + rh // 2))

    # connect rooms in leaf order (siblings are adjacent), L-shaped corridors
    for (ax, ay), (bx, by) in zip(centers, centers[1:]):
        if rng.random() < 0.5:
            carve_h(grid, ax, bx, ay); carve_v(grid, ay, by, bx)
        else:
            carve_v(grid, ay, by, ax); carve_h(grid, ax, bx, by)
    return grid, len(centers)


def carve_h(g, x1, x2, y):
    for x in range(min(x1, x2), max(x1, x2) + 1):
        g[y][x] = FLOOR


def carve_v(g, y1, y2, x):
    for y in range(min(y1, y2), max(y1, y2) + 1):
        g[y][x] = FLOOR


# ---------- cellular automata caves ----------
def caves(w: int, h: int, rng: random.Random, fill: float = 0.45, steps: int = 5) -> tuple[list[list[str]], int]:
    g = [[WALL if (x in (0, w - 1) or y in (0, h - 1) or rng.random() < fill) else FLOOR
          for x in range(w)] for y in range(h)]
    for _ in range(steps):
        n = new_grid(w, h)
        for y in range(1, h - 1):
            for x in range(1, w - 1):
                walls = sum(g[y + dy][x + dx] == WALL for dy in (-1, 0, 1) for dx in (-1, 0, 1) if dx or dy)
                n[y][x] = WALL if walls >= 5 else FLOOR if walls <= 3 else g[y][x]
        g = n
    # keep only the largest connected region so every floor tile is reachable
    regions = flood_regions(g)
    if regions:
        keep = max(regions, key=len)
        keep_set = set(keep)
        for y in range(h):
            for x in range(w):
                if g[y][x] == FLOOR and (x, y) not in keep_set:
                    g[y][x] = WALL
    return g, len(regions)


# ---------- validation ----------
def flood_regions(g) -> list[list[tuple[int, int]]]:
    h, w = len(g), len(g[0])
    seen = [[False] * w for _ in range(h)]
    regions = []
    for y in range(h):
        for x in range(w):
            if g[y][x] != FLOOR or seen[y][x]:
                continue
            region, q = [], deque([(x, y)])
            seen[y][x] = True
            while q:
                cx, cy = q.popleft()
                region.append((cx, cy))
                for nx, ny in ((cx + 1, cy), (cx - 1, cy), (cx, cy + 1), (cx, cy - 1)):
                    if 0 <= nx < w and 0 <= ny < h and not seen[ny][nx] and g[ny][nx] == FLOOR:
                        seen[ny][nx] = True
                        q.append((nx, ny))
            regions.append(region)
    return regions


def map_hash(g) -> str:
    return hashlib.sha256("\n".join("".join(r) for r in g).encode()).hexdigest()[:16]


def generate(algo, w, h, seed):
    rng = random.Random(seed)  # one RNG instance, owned by the generator, never global random
    return bsp(w, h, rng) if algo == "bsp" else caves(w, h, rng)


def validate(algo, g, count, min_rooms, min_open, max_open) -> list[str]:
    problems = []
    total = (len(g) - 2) * (len(g[0]) - 2)
    open_tiles = sum(r.count(FLOOR) for r in g)
    ratio = open_tiles / total
    regions = flood_regions(g)
    if len(regions) != 1:
        problems.append(f"{len(regions)} disconnected floor regions (expected 1)")
    if not (min_open <= ratio <= max_open):
        problems.append(f"open ratio {ratio:.2f} outside [{min_open}, {max_open}]")
    if algo == "bsp" and count < min_rooms:
        problems.append(f"{count} rooms < minimum {min_rooms}")
    return problems


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("--algo", choices=["bsp", "caves"], default="bsp")
    p.add_argument("--seed", type=int, default=1)
    p.add_argument("--width", type=int, default=60)
    p.add_argument("--height", type=int, default=30)
    p.add_argument("--min-rooms", type=int, default=4)
    p.add_argument("--min-open", type=float, default=0.15)
    p.add_argument("--max-open", type=float, default=0.70)
    p.add_argument("--expect-hash", help="fail unless the map hash equals this value")
    p.add_argument("--sweep", type=int, help="validate seeds 0..N-1 and report failures")
    p.add_argument("--quiet", action="store_true", help="do not print the map")
    a = p.parse_args()
    if a.width < 20 or a.height < 16:
        print("error: width >= 20 and height >= 16 required", file=sys.stderr)
        return 2

    if a.sweep:
        bad = []
        for s in range(a.sweep):
            g, n = generate(a.algo, a.width, a.height, s)
            probs = validate(a.algo, g, n, a.min_rooms, a.min_open, a.max_open)
            if probs:
                bad.append((s, probs))
        print(f"{a.algo}: {a.sweep - len(bad)}/{a.sweep} seeds valid")
        for s, probs in bad[:10]:
            print(f"  seed {s}: {'; '.join(probs)}")
        return 1 if bad else 0

    g, n = generate(a.algo, a.width, a.height, a.seed)
    g2, _ = generate(a.algo, a.width, a.height, a.seed)
    h1, h2 = map_hash(g), map_hash(g2)
    if not a.quiet:
        print("\n".join("".join(r) for r in g))
    label = "rooms" if a.algo == "bsp" else "raw regions"
    print(f"algo={a.algo} seed={a.seed} size={a.width}x{a.height} {label}={n} hash={h1}")
    status = 0
    if h1 != h2:
        print("FAIL: same seed produced different maps in one process (hidden nondeterminism)")
        status = 1
    for prob in validate(a.algo, g, n, a.min_rooms, a.min_open, a.max_open):
        print(f"FAIL: {prob}")
        status = 1
    if a.expect_hash and a.expect_hash != h1:
        print(f"FAIL: hash {h1} != expected {a.expect_hash} (generator output changed for this seed)")
        status = 1
    if status == 0:
        print("OK: connected, within open-area bounds, reproducible")
    return status


if __name__ == "__main__":
    sys.exit(main())