Procedural Generation skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Procedural Generation"
  short_description: "Seeded worlds that are always playable"
  default_prompt: "$procedural-generation Generate roguelike dungeons from a seed and guarantee every room is reachable"

#!/usr/bin/env python3
"""Seeded dungeon and cave generator for prototyping level rules.

Generates a map with BSP rooms or cellular-automata caves, then checks the
properties a generator must guarantee: reproducibility for the same seed,
full connectivity of floor tiles, and a minimum floor ratio.

Usage:
  python3 dungeon_gen.py --algo bsp --seed 42 --width 64 --height 36
  python3 dungeon_gen.py --algo caves --seed 7 --sweep 200   # test 200 seeds, print failures

Exit code 0 when every generated map passes, 1 otherwise. Standard library only.
"""
from __future__ import annotations

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

WALL, FLOOR = "#", "."


def bsp_dungeon(w: int, h: int, rng: random.Random, min_leaf: int = 8) -> list[list[str]]:
    grid = [[WALL] * w for _ in range(h)]
    leaves = [(1, 1, w - 2, h - 2)]
    changed = True
    while changed:
        changed = False
        nxt = []
        for x, y, lw, lh in leaves:
            if lw > 2 * min_leaf or lh > 2 * min_leaf:
                horizontal = lh > lw if abs(lw - lh) > 4 else rng.random() < 0.5
                if horizontal and lh > 2 * min_leaf:
                    cut = rng.randint(min_leaf, lh - min_leaf)
                    nxt += [(x, y, lw, cut), (x, y + cut, lw, lh - cut)]
                    changed = True
                    continue
                if not horizontal and lw > 2 * min_leaf:
                    cut = rng.randint(min_leaf, lw - min_leaf)
                    nxt += [(x, y, cut, lh), (x + cut, y, lw - cut, lh)]
                    changed = True
                    continue
            nxt.append((x, y, lw, lh))
        leaves = nxt

    centers = []
    for x, y, lw, lh in leaves:
        rw = rng.randint(max(3, lw // 2), max(3, lw - 2))
        rh = rng.randint(max(3, lh // 2), max(3, lh - 2))
        rx = x + rng.randint(0, max(0, lw - rw - 1))
        ry = y + rng.randint(0, max(0, lh - rh - 1))
        for yy in range(ry, min(ry + rh, h - 1)):
            for xx in range(rx, min(rx + rw, w - 1)):
                grid[yy][xx] = FLOOR
        centers.append((rx + rw // 2, ry + rh // 2))

    # Connect rooms in leaf order with L-shaped corridors (leaf order follows the split tree).
    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


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


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


def cave(w: int, h: int, rng: random.Random, fill: float = 0.45, steps: int = 5) -> list[list[str]]:
    grid = [[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):
        new = [row[:] for row in grid]
        for y in range(1, h - 1):
            for x in range(1, w - 1):
                walls = sum(grid[y + dy][x + dx] == WALL
                            for dy in (-1, 0, 1) for dx in (-1, 0, 1) if dx or dy)
                new[y][x] = WALL if walls >= 5 else FLOOR if walls <= 3 else grid[y][x]
        grid = new
    keep_largest_region(grid)
    return grid


def regions(grid) -> list[set[tuple[int, int]]]:
    h, w = len(grid), len(grid[0])
    seen: set[tuple[int, int]] = set()
    out = []
    for y in range(h):
        for x in range(w):
            if grid[y][x] != FLOOR or (x, y) in seen:
                continue
            region = {(x, y)}
            seen.add((x, y))
            q = deque([(x, y)])
            while q:
                cx, cy = q.popleft()
                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 grid[ny][nx] == FLOOR and (nx, ny) not in seen:
                        seen.add((nx, ny))
                        region.add((nx, ny))
                        q.append((nx, ny))
            out.append(region)
    return out


def keep_largest_region(grid) -> None:
    regs = regions(grid)
    if not regs:
        return
    largest = max(regs, key=len)
    for reg in regs:
        if reg is not largest:
            for x, y in reg:
                grid[y][x] = WALL


def generate(algo: str, seed: int, w: int, h: int) -> list[list[str]]:
    rng = random.Random(seed)          # one generator per map, never the global random
    return bsp_dungeon(w, h, rng) if algo == "bsp" else cave(w, h, rng)


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


def check(algo: str, seed: int, w: int, h: int, min_floor: float) -> tuple[list[str], list[list[str]]]:
    problems = []
    a, b = generate(algo, seed, w, h), generate(algo, seed, w, h)
    if digest(a) != digest(b):
        problems.append("not reproducible for the same seed")
    regs = regions(a)
    if len(regs) != 1:
        problems.append(f"{len(regs)} disconnected floor regions")
    floor = sum(row.count(FLOOR) for row in a) / (w * h)
    if floor < min_floor:
        problems.append(f"floor ratio {floor:.2f} below {min_floor:.2f}")
    return problems, a


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    p.add_argument("--algo", choices=["bsp", "caves"], default="bsp")
    p.add_argument("--seed", type=int, default=1)
    p.add_argument("--width", type=int, default=64)
    p.add_argument("--height", type=int, default=36)
    p.add_argument("--min-floor", type=float, default=0.2)
    p.add_argument("--sweep", type=int, default=0, help="check this many seeds starting at --seed")
    args = p.parse_args()

    if args.sweep:
        failures = 0
        for s in range(args.seed, args.seed + args.sweep):
            problems, _ = check(args.algo, s, args.width, args.height, args.min_floor)
            if problems:
                failures += 1
                print(f"seed {s}: " + "; ".join(problems))
        print(f"{args.algo}: {args.sweep - failures}/{args.sweep} seeds passed")
        return 1 if failures else 0

    problems, grid = check(args.algo, args.seed, args.width, args.height, args.min_floor)
    print("\n".join("".join(r) for r in grid))
    print(f"\nalgo={args.algo} seed={args.seed} size={args.width}x{args.height} hash={digest(grid)}")
    if problems:
        print("FAIL: " + "; ".join(problems))
        return 1
    print("OK: reproducible, connected, floor ratio within bounds")
    return 0


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