mapwright 0.2.0__py3-none-any.whl

mapwright/__init__.py

@@ -0,0 +1,62 @@
+"""mapwright — domain-neutral procedural fantasy map & world generation.
+
+A dependency-light (numpy-only) library:
+
+  * :class:`SeededRNG` — one seed drives everything; ``.derive(label)`` gives
+    independent, reproducible sub-streams.
+  * :class:`NameGenerator` — order-k Markov place/person names in several culture
+    styles, seed-reproducible across processes.
+  * :class:`RegionalTerrainGenerator` — Voronoi cells (Lloyd-relaxed) → heightmap
+    → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers
+    → latitude/elevation climate → Whittaker biomes. Returns neutral data
+    (:class:`Biome`, :class:`TerrainResult`); mapping it onto a host app's tile
+    vocabulary is the caller's job.
+  * :class:`RegionalSVGRenderer` — shaded-relief (hillshade) SVG: biome polygons,
+    coastline, rivers, labelled :class:`Marker` points.
+
+Built clean-room from the published ideas in Azgaar's Fantasy-Map-Generator (MIT)
+and rlguy/Mewo2's FantasyMapGenerator (Zlib). See NOTICE.
+
+Quickstart::
+
+    from mapwright import SeededRNG, RegionalTerrainGenerator, RegionalSVGRenderer
+    terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(60, 40)
+    svg = RegionalSVGRenderer().render(terrain)
+"""
+
+from .config import WorldMapConfig, PRESETS
+from .dungeon import Dungeon, DungeonConfig, DungeonGenerator, Rect
+from .names import NameGenerator, MarkovNameGenerator, NAMEBASES
+from .rng import SeededRNG
+from .svg_renderer import Marker, RegionalSVGRenderer
+from .terrain import (
+    Biome,
+    River,
+    TerrainCell,
+    TerrainResult,
+    RegionalTerrainGenerator,
+    compute_cell_polygons,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "SeededRNG",
+    "WorldMapConfig",
+    "PRESETS",
+    "NameGenerator",
+    "MarkovNameGenerator",
+    "NAMEBASES",
+    "Biome",
+    "River",
+    "TerrainCell",
+    "TerrainResult",
+    "RegionalTerrainGenerator",
+    "compute_cell_polygons",
+    "Marker",
+    "RegionalSVGRenderer",
+    "Dungeon",
+    "DungeonConfig",
+    "DungeonGenerator",
+    "Rect",
+]

mapwright/config.py

@@ -0,0 +1,154 @@
+"""Tunable world-generation parameters.
+
+``WorldMapConfig`` is the single knob-set that shapes a generated world. Every
+field is a bounded scalar or small int with a clear semantic and a default that
+yields a balanced single-continent world — so it doubles as a **schema a host
+app (or an LLM) can populate from a description**: "a frozen archipelago of
+scattered isles" → ``WorldMapConfig(continents=7, sea_level=0.55, temperature=-0.8)``.
+
+The library deliberately depends only on numpy, so this is a plain dataclass (no
+pydantic). A host that wants JSON-schema/LLM population can mirror these fields
+in its own model and call :meth:`WorldMapConfig.from_dict` (which clamps to
+valid ranges, so a sloppy LLM payload can't produce a broken world).
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, fields
+
+
+def _clamp(value: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, value))
+
+
+# Single source of truth for every knob: (name, type, min, max, description).
+# Drives both __post_init__ clamping and json_schema(), so the validation
+# behaviour and the published contract can never disagree.
+_SPEC: list[tuple] = [
+    ("sea_level", float, 0.05, 0.9,
+     "Fraction of the height range below water. Higher = more ocean."),
+    ("continents", int, 1, 24,
+     "Number of major landmasses. 1 = single continent; 4-8 = archipelago."),
+    ("continent_spread", float, 0.0, 1.0,
+     "0 = landmasses cluster at the centre; 1 = pushed toward the edges."),
+    ("edge_falloff", float, 0.0, 2.0,
+     "0 = land may reach the map border; 1 = strong 'ringed by sea' coastline."),
+    ("mountain_density", float, 0.0, 1.0,
+     "Abundance and height of hills/ranges."),
+    ("roughness", float, 0.0, 1.0,
+     "Terrain detail (number of erosion passes)."),
+    ("temperature", float, -1.0, 1.0,
+     "Global temperature bias: -1 frozen .. +1 scorching."),
+    ("moisture", float, -1.0, 1.0,
+     "Global moisture bias: -1 arid .. +1 drowned."),
+    ("river_density", float, 0.0, 1.0,
+     "How readily rivers are traced; more = more, smaller rivers."),
+]
+
+
+@dataclass
+class WorldMapConfig:
+    """Knobs for :meth:`RegionalTerrainGenerator.generate`. Defaults = baseline."""
+
+    # --- Topology / landmass ---
+    sea_level: float = 0.32
+    """0..1 — fraction of the height range below water. Higher ⇒ more ocean."""
+    continents: int = 1
+    """Number of major landmasses. 1 = single continent; 4–8 ⇒ archipelago."""
+    continent_spread: float = 0.5
+    """0 ⇒ landmasses cluster at the centre; 1 ⇒ pushed toward the edges."""
+    edge_falloff: float = 1.0
+    """0 ⇒ land may reach the map border; 1 ⇒ strong 'ringed by sea' coastline."""
+
+    # --- Relief ---
+    mountain_density: float = 0.5
+    """0..1 — abundance and height of hills/ranges."""
+    roughness: float = 0.5
+    """0..1 — terrain detail (drives the number of erosion passes)."""
+
+    # --- Climate ---
+    temperature: float = 0.0
+    """-1 (frozen) .. +1 (scorching) — global temperature bias."""
+    moisture: float = 0.0
+    """-1 (arid) .. +1 (drowned) — global moisture bias."""
+
+    # --- Hydrology ---
+    river_density: float = 0.5
+    """0..1 — how readily rivers are traced (more ⇒ more, smaller rivers)."""
+
+    def __post_init__(self) -> None:
+        # Clamp everything so out-of-range inputs (e.g. from an LLM) are safe.
+        for name, typ, lo, hi, _desc in _SPEC:
+            value = _clamp(getattr(self, name), lo, hi)
+            setattr(self, name, int(value) if typ is int else float(value))
+
+    # -- serialisation / interop ----------------------------------------
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "WorldMapConfig":
+        """Build from a (possibly partial / noisy) mapping; unknown keys ignored."""
+        known = {f.name for f in fields(cls)}
+        return cls(**{k: v for k, v in data.items() if k in known})
+
+    @classmethod
+    def json_schema(cls) -> dict:
+        """A JSON Schema (draft 2020-12) describing this config.
+
+        This is mapwright's machine-readable **contract** for world parameters:
+        a host app or an LLM can validate/generate payloads against it, then feed
+        them through :meth:`from_dict` (which additionally clamps). Generated from
+        the same field spec used for clamping, so schema and behaviour can't drift.
+        """
+        defaults = cls()
+        properties = {
+            name: {
+                "type": "integer" if typ is int else "number",
+                "minimum": lo,
+                "maximum": hi,
+                "default": getattr(defaults, name),
+                "description": desc,
+            }
+            for name, typ, lo, hi, desc in _SPEC
+        }
+        return {
+            "$schema": "https://json-schema.org/draft/2020-12/schema",
+            "title": "WorldMapConfig",
+            "description": "Parameters that shape a mapwright world.",
+            "type": "object",
+            "additionalProperties": False,
+            "properties": properties,
+        }
+
+    # -- presets (also demonstrate the knobs & seed LLM choices) --------
+
+    @classmethod
+    def preset(cls, name: str) -> "WorldMapConfig":
+        """A named starting point. Raises KeyError for an unknown preset."""
+        return cls.from_dict(dict(PRESETS[name]))
+
+    @staticmethod
+    def preset_names() -> list[str]:
+        return sorted(PRESETS.keys())
+
+
+# Named presets — ready-made worlds and good LLM anchors. Each maps to a kind of
+# narrative setting; a host can expose these by name or let an LLM pick + tweak.
+PRESETS: dict[str, dict] = {
+    "continent": {},  # the balanced default
+    "pangaea": {"continents": 1, "sea_level": 0.22, "continent_spread": 0.15,
+                "edge_falloff": 0.55},
+    "archipelago": {"continents": 7, "sea_level": 0.55, "continent_spread": 0.75,
+                    "mountain_density": 0.4},
+    "highlands": {"continents": 1, "mountain_density": 0.95, "roughness": 0.75,
+                  "river_density": 0.7},
+    "desert": {"temperature": 0.85, "moisture": -0.85, "sea_level": 0.28,
+               "mountain_density": 0.25, "river_density": 0.12},
+    "arctic": {"temperature": -0.85, "moisture": 0.1, "mountain_density": 0.5},
+    "tropical": {"temperature": 0.6, "moisture": 0.85, "river_density": 0.85,
+                 "mountain_density": 0.55},
+    "islands": {"continents": 12, "sea_level": 0.62, "continent_spread": 0.85,
+                "mountain_density": 0.3},
+}

mapwright/dungeon.py

@@ -0,0 +1,229 @@
+"""Procedural dungeon generation: BSP rooms + minimum-spanning-tree corridors.
+
+Clean-room from the ideas of two permissively-licensed generators:
+  * **BSP space partitioning** — Adrian Kulawik's *Dungeon-Generator* (MIT): split
+    the map recursively into leaves and place one room per leaf, so rooms never
+    overlap and space is used evenly.
+  * **MST connectivity** — *donjuan* (CC0): connect rooms with a minimum spanning
+    tree (Prim's) so every room is reachable with no redundant corridors, then add
+    a few extra edges for loops.
+
+Domain-neutral: returns rooms (rectangles), carved corridor cells, and a boolean
+walkable grid. A host maps these onto its own tiles/doors/encounters. Fully
+seed-deterministic via :class:`SeededRNG`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from .rng import SeededRNG
+
+
+@dataclass
+class Rect:
+    """An axis-aligned room rectangle (integer tile coordinates)."""
+
+    x: int
+    y: int
+    w: int
+    h: int
+
+    @property
+    def cx(self) -> int:
+        return self.x + self.w // 2
+
+    @property
+    def cy(self) -> int:
+        return self.y + self.h // 2
+
+    @property
+    def center(self) -> tuple[int, int]:
+        return (self.cx, self.cy)
+
+    def intersects(self, other: "Rect", pad: int = 0) -> bool:
+        return (
+            self.x - pad < other.x + other.w
+            and self.x + self.w + pad > other.x
+            and self.y - pad < other.y + other.h
+            and self.y + self.h + pad > other.y
+        )
+
+
+@dataclass
+class DungeonConfig:
+    """Knobs for dungeon generation. Defaults give a balanced multi-room layout."""
+
+    min_leaf: int = 8
+    """Smallest BSP leaf (tiles) — a leaf this size or smaller is not split."""
+    room_min: int = 3
+    """Smallest room edge length."""
+    room_padding: int = 1
+    """Gap kept between a room and its leaf's edges."""
+    split_jitter: float = 0.35
+    """0 = always split a leaf in half; up to 0.5 = split position varies."""
+    extra_corridor_chance: float = 0.12
+    """Probability per non-tree room-pair of an extra (loop) corridor."""
+
+
+@dataclass
+class Dungeon:
+    """Generated dungeon: rooms, carved corridor cells, and a walkable grid."""
+
+    width: int
+    height: int
+    rooms: list[Rect]
+    corridors: list[tuple[int, int]]
+    grid: np.ndarray  # bool [height, width]; True = floor
+    edges: list[tuple[int, int]] = field(default_factory=list)  # connected room-index pairs
+
+    def ascii(self) -> str:
+        """A quick ``#``/``.`` map (rooms+corridors as floor) for eyeballing/tests."""
+        rows = []
+        for y in range(self.height):
+            rows.append("".join("." if self.grid[y, x] else "#" for x in range(self.width)))
+        return "\n".join(rows)
+
+
+class DungeonGenerator:
+    """Builds a :class:`Dungeon` for a ``width×height`` grid."""
+
+    def __init__(self, rng: SeededRNG):
+        self._rng = rng.derive("dungeon")
+
+    def generate(
+        self, width: int, height: int, config: DungeonConfig | None = None
+    ) -> Dungeon:
+        cfg = config or DungeonConfig()
+        leaves = self._bsp(0, 0, width, height, cfg)
+        rooms = [r for leaf in leaves if (r := self._room_in_leaf(leaf, cfg))]
+
+        grid = np.zeros((height, width), dtype=bool)
+        for r in rooms:
+            grid[r.y : r.y + r.h, r.x : r.x + r.w] = True
+
+        corridors, edges = self._connect(rooms, grid, cfg)
+        return Dungeon(width, height, rooms, corridors, grid, edges)
+
+    # -- 1. BSP partitioning --------------------------------------------
+
+    def _bsp(self, x: int, y: int, w: int, h: int, cfg: DungeonConfig) -> list[Rect]:
+        """Recursively split a region into leaves no smaller than ``min_leaf``."""
+        # Decide whether (and how) to split. Stop when too small to yield two
+        # viable children in either axis.
+        can_h = w >= 2 * cfg.min_leaf
+        can_v = h >= 2 * cfg.min_leaf
+        if not can_h and not can_v:
+            return [Rect(x, y, w, h)]
+
+        # Prefer splitting the longer axis so leaves stay squarish.
+        if can_h and can_v:
+            split_horizontal = w > h if abs(w - h) > cfg.min_leaf else self._rng.chance(0.5)
+        else:
+            split_horizontal = can_h
+
+        if split_horizontal:
+            lo, hi = cfg.min_leaf, w - cfg.min_leaf
+            cut = self._jittered_cut(lo, hi, w, cfg)
+            return (self._bsp(x, y, cut, h, cfg)
+                    + self._bsp(x + cut, y, w - cut, h, cfg))
+        else:
+            lo, hi = cfg.min_leaf, h - cfg.min_leaf
+            cut = self._jittered_cut(lo, hi, h, cfg)
+            return (self._bsp(x, y, w, cut, cfg)
+                    + self._bsp(x, y + cut, w, h - cut, cfg))
+
+    def _jittered_cut(self, lo: int, hi: int, span: int, cfg: DungeonConfig) -> int:
+        mid = span / 2
+        jitter = span * cfg.split_jitter
+        cut = int(round(self._rng.uniform(mid - jitter, mid + jitter)))
+        return max(lo, min(hi, cut))
+
+    # -- 2. Rooms --------------------------------------------------------
+
+    def _room_in_leaf(self, leaf: Rect, cfg: DungeonConfig) -> Rect | None:
+        """Place a random room inside a leaf, inset by ``room_padding``."""
+        pad = cfg.room_padding
+        max_w = leaf.w - 2 * pad
+        max_h = leaf.h - 2 * pad
+        if max_w < cfg.room_min or max_h < cfg.room_min:
+            return None
+        rw = self._rng.randint(cfg.room_min, max_w)
+        rh = self._rng.randint(cfg.room_min, max_h)
+        rx = leaf.x + pad + self._rng.randint(0, max_w - rw)
+        ry = leaf.y + pad + self._rng.randint(0, max_h - rh)
+        return Rect(rx, ry, rw, rh)
+
+    # -- 3. Corridors (MST + loops) -------------------------------------
+
+    def _connect(
+        self, rooms: list[Rect], grid: np.ndarray, cfg: DungeonConfig
+    ) -> tuple[list[tuple[int, int]], list[tuple[int, int]]]:
+        """Connect rooms with a Prim MST (+ optional loops); carve L-corridors."""
+        n = len(rooms)
+        corridors: list[tuple[int, int]] = []
+        edges: list[tuple[int, int]] = []
+        if n < 2:
+            return corridors, edges
+
+        centers = [r.center for r in rooms]
+
+        def dist2(i: int, j: int) -> int:
+            (ax, ay), (bx, by) = centers[i], centers[j]
+            return (ax - bx) ** 2 + (ay - by) ** 2
+
+        # Prim's MST over room centers (dense graph, n is small).
+        in_tree = {0}
+        while len(in_tree) < n:
+            best = None
+            best_d = None
+            for i in in_tree:
+                for j in range(n):
+                    if j in in_tree:
+                        continue
+                    d = dist2(i, j)
+                    if best_d is None or d < best_d:
+                        best_d, best = d, (i, j)
+            i, j = best
+            in_tree.add(j)
+            edges.append((i, j))
+
+        # A few extra edges → loops (less tree-like, more interesting).
+        for i in range(n):
+            for j in range(i + 1, n):
+                if (i, j) in edges or (j, i) in edges:
+                    continue
+                if self._rng.chance(cfg.extra_corridor_chance):
+                    edges.append((i, j))
+
+        for i, j in edges:
+            corridors.extend(self._carve_l(centers[i], centers[j], grid))
+        return corridors, edges
+
+    def _carve_l(
+        self, a: tuple[int, int], b: tuple[int, int], grid: np.ndarray
+    ) -> list[tuple[int, int]]:
+        """Carve an L-shaped corridor between two points; return the new cells."""
+        (ax, ay), (bx, by) = a, b
+        cells: list[tuple[int, int]] = []
+        h_first = self._rng.chance(0.5)
+        corner = (bx, ay) if h_first else (ax, by)
+
+        def line(p: tuple[int, int], q: tuple[int, int]) -> None:
+            (px, py), (qx, qy) = p, q
+            if px == qx:
+                for y in range(min(py, qy), max(py, qy) + 1):
+                    if not grid[y, px]:
+                        grid[y, px] = True
+                        cells.append((px, y))
+            else:
+                for x in range(min(px, qx), max(px, qx) + 1):
+                    if not grid[py, x]:
+                        grid[py, x] = True
+                        cells.append((x, py))
+
+        line(a, corner)
+        line(corner, b)
+        return cells