Procedural dungeon

rooms and corridors on a TileMap

▶ Run in browser

Tags: 2d tilemap procgen dungeon collision

Places non-overlapping rooms at random, links each to the previous one with an L-shaped corridor, and renders the result as wall and floor tiles. Generation is a pure function of the seed, so the same number always yields the same dungeon. A player dot walks the map with grid-based wall collision. Controls: WASD / arrows move, R rolls a new seed, [ / ] step the seed, Esc quits. Headless self-check: uv run python examples/features/2d/procgen_dungeon.py –test

What it demonstrates

• A self-contained, deterministic dungeon generator (generate_dungeon) you can lift straight into a game: random.Random(seed) in, grid + room list out.

• Reachability by construction: every room is carved, then connected to the one placed before it, so the whole floor is one region.

• TileMapLayer.set_cells(): the entire grid rewritten in one vectorised call, which is what makes instant regeneration cheap.

• Collision against the grid, not against physics bodies: the player’s box is tested per axis with can_stand, the pattern roguelikes and grid games use.

Run: uv run python examples/features/2d/procgen_dungeon.py

Source

"""Procedural dungeon: rooms and corridors on a TileMap

Places non-overlapping rooms at random, links each to the previous one with an
L-shaped corridor, and renders the result as wall and floor tiles. Generation
is a pure function of the seed, so the same number always yields the same
dungeon. A player dot walks the map with grid-based wall collision.
Controls: WASD / arrows move, R rolls a new seed, [ / ] step the seed, Esc quits.
Headless self-check: uv run python examples/features/2d/procgen_dungeon.py --test

# /// simvx
# tags = ["2d", "tilemap", "procgen", "dungeon", "collision"]
# web = { root = "DungeonDemo", width = 960, height = 540 }
# ///

## What it demonstrates
- A self-contained, deterministic dungeon generator (`generate_dungeon`) you
  can lift straight into a game: random.Random(seed) in, grid + room list out.
- Reachability by construction: every room is carved, then connected to the
  one placed before it, so the whole floor is one region.
- TileMapLayer.set_cells(): the entire grid rewritten in one vectorised call,
  which is what makes instant regeneration cheap.
- Collision against the grid, not against physics bodies: the player's box is
  tested per axis with `can_stand`, the pattern roguelikes and grid games use.

Run: uv run python examples/features/2d/procgen_dungeon.py
"""

from __future__ import annotations

import random
from collections import deque
from dataclasses import dataclass

import numpy as np

from simvx.core import (
    AnchorPreset,
    CanvasLayer,
    Input,
    InputMap,
    Key,
    Label,
    Node2D,
    Sprite2D,
    TileMap,
    TileSet,
    Vec2,
)
from simvx.graphics import App

WIDTH, HEIGHT = 960, 540
TILE = 16
GRID_W, GRID_H = 60, 32  # 960 x 512 px of map; the last 28 px are the HUD strip

FLOOR, WALL = 0, 1  # grid values; also the tile ids, atlas is built to match

PLAYER_HALF = 5.0  # half-extent of the player's collision box, px
PLAYER_SPEED = 150.0


# -- Generator ----------------------------------------------------------------


@dataclass(frozen=True)
class Room:
    """A carved room: interior rectangle in grid cells."""

    x: int
    y: int
    w: int
    h: int

    @property
    def centre(self) -> tuple[int, int]:
        return self.x + self.w // 2, self.y + self.h // 2


@dataclass(frozen=True)
class Dungeon:
    """Generator output: (H, W) uint8 grid of FLOOR/WALL plus the room list."""

    grid: np.ndarray
    rooms: list[Room]
    seed: int


def generate_dungeon(
    width: int,
    height: int,
    seed: int,
    *,
    room_attempts: int = 40,
    room_min: int = 4,
    room_max: int = 8,
) -> Dungeon:
    """Generate a rooms-and-corridors dungeon, deterministic for a given seed.

    Classic room-place-and-connect: try `room_attempts` random rectangles,
    keep the ones that fit with a one-cell wall gap, and join each kept room
    to the previously kept one with an L-shaped corridor (axis order chosen at
    random). Connecting only ever to an already-connected room is what makes
    the whole floor reachable without any post-hoc repair pass.
    """
    rng = random.Random(seed)
    grid = np.full((height, width), WALL, dtype=np.uint8)
    rooms: list[Room] = []

    for _ in range(room_attempts):
        w = rng.randint(room_min, room_max)
        h = rng.randint(room_min, room_max)
        room = Room(rng.randint(1, width - w - 1), rng.randint(1, height - h - 1), w, h)
        # Reject anything that would touch an existing room (1-cell gap kept).
        if any(
            room.x - 1 < r.x + r.w
            and room.x + room.w + 1 > r.x
            and room.y - 1 < r.y + r.h
            and room.y + room.h + 1 > r.y
            for r in rooms
        ):
            continue
        grid[room.y : room.y + room.h, room.x : room.x + room.w] = FLOOR
        if rooms:
            _carve_corridor(grid, room.centre, rooms[-1].centre, rng)
        rooms.append(room)

    return Dungeon(grid, rooms, seed)


def _carve_corridor(grid: np.ndarray, a: tuple[int, int], b: tuple[int, int], rng: random.Random) -> None:
    """Carve an L-shaped floor corridor between two cell centres."""
    (ax, ay), (bx, by) = a, b
    corner = (bx, ay) if rng.random() < 0.5 else (ax, by)
    for x0, y0, x1, y1 in ((ax, ay, *corner), (*corner, bx, by)):
        grid[min(y0, y1) : max(y0, y1) + 1, min(x0, x1) : max(x0, x1) + 1] = FLOOR


def can_stand(grid: np.ndarray, x: float, y: float, half: float = PLAYER_HALF) -> bool:
    """True if a box of half-extent `half` centred at world (x, y) is all floor."""
    cx0, cx1 = int((x - half) // TILE), int((x + half) // TILE)
    cy0, cy1 = int((y - half) // TILE), int((y + half) // TILE)
    h, w = grid.shape
    if cx0 < 0 or cy0 < 0 or cx1 >= w or cy1 >= h:
        return False
    return bool(np.all(grid[cy0 : cy1 + 1, cx0 : cx1 + 1] == FLOOR))


def reachable_floor(grid: np.ndarray, start: tuple[int, int]) -> int:
    """Count floor cells reachable from `start` via 4-neighbour flood fill."""
    h, w = grid.shape
    seen = np.zeros_like(grid, dtype=bool)
    queue = deque([start])
    seen[start[1], start[0]] = True
    count = 0
    while queue:
        x, y = queue.popleft()
        count += 1
        for nx, ny in ((x + 1, y), (x - 1, y), (x, y + 1), (x, y - 1)):
            if 0 <= nx < w and 0 <= ny < h and not seen[ny, nx] and grid[ny, nx] == FLOOR:
                seen[ny, nx] = True
                queue.append((nx, ny))
    return count


# -- Rendering ----------------------------------------------------------------


def _make_atlas() -> np.ndarray:
    """Two 16 px tiles side by side: floor (id 0, dark) then wall (id 1, blue-grey)."""
    rng = np.random.RandomState(11)
    atlas = np.zeros((TILE, TILE * 2, 4), dtype=np.uint8)
    for tid, base in ((FLOOR, (52, 46, 42)), (WALL, (96, 104, 132))):
        noise = rng.randint(-10, 11, size=(TILE, TILE, 1))
        tile = np.clip(np.array(base).reshape(1, 1, 3) + noise, 0, 255).astype(np.uint8)
        x0 = tid * TILE
        atlas[:, x0 : x0 + TILE, :3] = tile
        atlas[:, x0 : x0 + TILE, 3] = 255
    # A darker mortar line along each wall tile's edges reads as brickwork.
    atlas[0, TILE:, :3] = atlas[:, TILE, :3] = (60, 66, 88)
    return atlas


def _make_player_texture(size: int = 12) -> np.ndarray:
    """A warm disc with a dark outline."""
    img = np.zeros((size, size, 4), dtype=np.uint8)
    yy, xx = np.mgrid[0:size, 0:size]
    d = np.hypot(xx - (size - 1) / 2, yy - (size - 1) / 2)
    img[d <= size / 2 - 0.5] = (40, 28, 10, 255)
    img[d <= size / 2 - 2.0] = (255, 205, 70, 255)
    return img


class DungeonDemo(Node2D):
    """TileMap-rendered dungeon with a grid-collided player and live reseeding."""

    def on_ready(self):
        InputMap.add_action("move_left", [Key.A, Key.LEFT])
        InputMap.add_action("move_right", [Key.D, Key.RIGHT])
        InputMap.add_action("move_up", [Key.W, Key.UP])
        InputMap.add_action("move_down", [Key.S, Key.DOWN])
        InputMap.add_action("regen", [Key.R])
        InputMap.add_action("seed_down", [Key.LEFT_BRACKET])
        InputMap.add_action("seed_up", [Key.RIGHT_BRACKET])
        InputMap.add_action("quit", [Key.ESCAPE])

        self._tilemap = self.add_child(TileMap(name="Dungeon"))
        self._tilemap.tile_set = TileSet.from_atlas_array(
            _make_atlas(), width=TILE * 2, height=TILE, tile_size=(TILE, TILE)
        )
        self._tilemap.cell_size = (TILE, TILE)

        self._player = self.add_child(Sprite2D(texture=_make_player_texture(), width=12, height=12, name="Player"))

        hud = self.add_child(CanvasLayer(name="HUD", layer=CanvasLayer.Band.UI))
        self._hud = hud.add_child(Label("", name="Status"))
        self._hud.set_anchor_preset(AnchorPreset.BOTTOM_WIDE)
        self._hud.margin_left = 12
        self._hud.margin_right = 12
        self._hud.margin_top = -26
        self._hud.margin_bottom = -4
        self._hud.font_size = 15.0

        self._regenerate(seed=1)

    def _regenerate(self, seed: int) -> None:
        """Rebuild the dungeon for `seed` and drop the player in the first room."""
        self._dungeon = generate_dungeon(GRID_W, GRID_H, seed)
        # One bulk write replaces every cell: grid values ARE the tile ids.
        self._tilemap.get_layer(0).set_cells(self._dungeon.grid.astype(np.int32))
        cx, cy = self._dungeon.rooms[0].centre
        self._player.position = Vec2((cx + 0.5) * TILE, (cy + 0.5) * TILE)
        self._hud.text = (
            f"Seed {seed}   rooms {len(self._dungeon.rooms)}   "
            "R: new seed   [ / ]: step seed   WASD / arrows: move   Esc: quit"
        )

    def on_update(self, dt: float):
        if Input.is_action_just_pressed("quit"):
            self.app.quit()
            return
        if Input.is_action_just_pressed("regen"):
            self._regenerate(seed=random.randrange(1_000_000))
        elif Input.is_action_just_pressed("seed_down"):
            self._regenerate(seed=self._dungeon.seed - 1)
        elif Input.is_action_just_pressed("seed_up"):
            self._regenerate(seed=self._dungeon.seed + 1)

        move = Input.get_vector("move_left", "move_right", "move_up", "move_down")
        if move.x == 0 and move.y == 0:
            return
        # Per-axis moves so a blocked axis does not stop the other (wall sliding).
        grid, pos = self._dungeon.grid, self._player.position
        x, y = pos.x, pos.y
        if move.x != 0 and can_stand(grid, x + move.x * PLAYER_SPEED * dt, y):
            x += move.x * PLAYER_SPEED * dt
        if move.y != 0 and can_stand(grid, x, y + move.y * PLAYER_SPEED * dt):
            y += move.y * PLAYER_SPEED * dt
        self._player.position = Vec2(x, y)


# -- Self-check ---------------------------------------------------------------


def _selftest() -> bool:
    ok = True

    def check(label: str, passed: bool, detail: str) -> None:
        nonlocal ok
        ok = ok and passed
        print(f"{'ok  ' if passed else 'FAIL'} {label}: {detail}")

    d1 = generate_dungeon(GRID_W, GRID_H, seed=7)
    d2 = generate_dungeon(GRID_W, GRID_H, seed=7)
    check(
        "same seed reproduces the dungeon",
        bool(np.array_equal(d1.grid, d2.grid)) and d1.rooms == d2.rooms,
        f"{len(d1.rooms)} rooms both times",
    )

    d3 = generate_dungeon(GRID_W, GRID_H, seed=8)
    check("a different seed differs", not np.array_equal(d1.grid, d3.grid), "seed 7 vs 8")

    border = np.concatenate([d1.grid[0], d1.grid[-1], d1.grid[:, 0], d1.grid[:, -1]])
    check("the border stays solid wall", bool(np.all(border == WALL)), f"{len(border)} edge cells")

    carved = all(np.all(d1.grid[r.y : r.y + r.h, r.x : r.x + r.w] == FLOOR) for r in d1.rooms)
    check("every room interior is floor", carved, f"{len(d1.rooms)} rooms checked")

    # Reachability across a spread of seeds: the flood fill from the first
    # room must touch every floor cell, or a room was carved but never linked.
    for seed in (1, 7, 42, 12345):
        d = generate_dungeon(GRID_W, GRID_H, seed=seed)
        floor_total = int(np.sum(d.grid == FLOOR))
        reached = reachable_floor(d.grid, d.rooms[0].centre)
        check(
            f"seed {seed}: all floor is reachable",
            reached == floor_total and len(d.rooms) >= 5,
            f"{reached}/{floor_total} cells, {len(d.rooms)} rooms",
        )

    # Collision: a room centre is standable, the wall beside the map is not,
    # and a spot flush against the border wall rejects the overlapping box.
    cx, cy = d1.rooms[0].centre
    check(
        "the spawn point is standable",
        can_stand(d1.grid, (cx + 0.5) * TILE, (cy + 0.5) * TILE),
        f"room centre cell ({cx}, {cy})",
    )
    check("a wall cell blocks the player", not can_stand(d1.grid, TILE * 0.5, TILE * 0.5), "border cell (0, 0)")
    check(
        "a box overlapping a wall is blocked",
        not can_stand(d1.grid, TILE + PLAYER_HALF - 1, (cy + 0.5) * TILE),
        "flush against the west border",
    )

    print("SELFTEST:", "PASS" if ok else "FAIL")
    return ok


if __name__ == "__main__":
    import sys

    if "--test" in sys.argv:
        sys.exit(0 if _selftest() else 1)
    App(title="Procedural Dungeon", width=WIDTH, height=HEIGHT).run(DungeonDemo())