mapwright 0.2.0__tar.gz

mapwright-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check src tests
+      - name: Test (pytest)
+        run: pytest -q

mapwright-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Publishes to PyPI via Trusted Publishing (OIDC) when a GitHub Release is
+# published. No API token needed — PyPI verifies this repo + workflow + env.
+# To release: tag (vX.Y.Z) and create a GitHub Release for that tag, e.g.
+#   gh release create v0.2.0 --generate-notes
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:          # allow manual publish of the current main (version in pyproject)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # must match the "Environment name" in PyPI's publisher config
+    permissions:
+      id-token: write          # REQUIRED for Trusted Publishing (OIDC)
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

mapwright-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtualenvs
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Generated preview artifacts
+*.preview.svg
+*.preview.png

mapwright-0.2.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to mapwright are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+**Public API** = the names exported in `mapwright.__all__` (pinned by
+`tests/test_api_contract.py`). While the version is `0.x`, minor versions may
+make breaking changes; these will always be noted here.
+
+## [Unreleased]
+
+## [0.2.0] — 2026-06-01
+
+### Added
+- **Dungeon generation** — `DungeonGenerator` → `Dungeon` (+ `DungeonConfig`, `Rect`):
+  BSP space-partitioning rooms (no overlap) connected by a Prim minimum-spanning-tree
+  of L-corridors, plus optional loop corridors. Returns rooms, carved corridor cells,
+  and a boolean walkable grid; `Dungeon.ascii()` for quick previews. Clean-room from
+  Dungeon-Generator (MIT, BSP) and donjuan (CC0, MST connectivity).
+
+## [0.1.0] — 2026-06-01
+
+Initial release. Domain-neutral procedural fantasy map & world generation.
+
+### Added
+- `SeededRNG` — one-seed determinism with `.derive(label)` sub-streams; unifies
+  the stdlib and numpy generators. Reproducible across processes.
+- `NameGenerator` / `MarkovNameGenerator` — order-k Markov place/person names
+  over hand-authored culture namebases (`NAMEBASES`); hash-seed independent.
+- `RegionalTerrainGenerator` → `TerrainResult` — Voronoi cells (Lloyd-relaxed),
+  Planchon–Darboux depression fill, hydraulic + creep erosion, river tracing,
+  latitude/elevation climate, and a Whittaker `Biome` matrix.
+- `WorldMapConfig` — bounded, documented world parameters (sea level, continents,
+  climate, mountains, rivers) with `from_dict` clamping, named `PRESETS`, and a
+  `json_schema()` contract for host/LLM population.
+- `RegionalSVGRenderer` + `Marker` — shaded-relief (hillshade) SVG: biome
+  polygons, coastline, rivers, labelled markers. `compute_cell_polygons` rebuilds
+  convex Voronoi polygons via half-plane clipping.
+
+[Unreleased]: https://github.com/sligara7/mapwright/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sligara7/mapwright/releases/tag/v0.1.0

mapwright-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Sligar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mapwright-0.2.0/NOTICE

@@ -0,0 +1,28 @@
+mapwright
+Copyright (c) 2026 Anthony Sligar
+Licensed under the MIT License (see LICENSE).
+
+------------------------------------------------------------------------------
+Acknowledgements
+------------------------------------------------------------------------------
+
+mapwright's algorithms were implemented clean-room from the publicly described
+ideas and techniques of the following open-source projects. No source code was
+copied from them; this NOTICE credits the lineage of the techniques.
+
+* Azgaar's Fantasy-Map-Generator (MIT License)
+    https://github.com/Azgaar/Fantasy-Map-Generator
+    Ideas: jittered-grid Voronoi with Lloyd relaxation, flux-accumulation
+    rivers, temperature x precipitation -> biome matrix, Markov per-culture
+    name generation, single-seed determinism, SVG cartographic rendering.
+
+* "Generating fantasy maps" by Martin O'Leary (mewo2), and its C++ implementation
+  FantasyMapGenerator by Ryan L. Guy (rlguy) (Zlib License)
+    https://mewo2.com/notes/terrain/
+    https://github.com/rlguy/FantasyMapGenerator
+    Ideas: hydraulic + creep erosion (river * sqrt(flux) * slope + creep *
+    slope^2), Planchon-Darboux depression filling for guaranteed drainage,
+    slope-normal hillshade ("shaded relief") rendering.
+
+The name lists ("namebases") bundled with mapwright are original, hand-authored
+data, not derived from any third-party generator.

mapwright-0.2.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: mapwright
+Version: 0.2.0
+Summary: Domain-neutral procedural fantasy map & world generation: Voronoi terrain, hydraulic erosion, biomes, rivers, Markov place-names, and shaded-relief SVG.
+Project-URL: Homepage, https://github.com/sligara7/mapwright
+Project-URL: Repository, https://github.com/sligara7/mapwright
+Author: Anthony Sligar
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: biomes,erosion,fantasy-map,procedural-generation,svg,terrain,ttrpg,voronoi,worldgen
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mapwright
+
+> ⚠️ **Early development (v0.1, alpha).** The API is still moving and may change without
+> notice between versions. Extracted from a working application; usable today, but pin a
+> commit if you depend on it.
+
+**Domain-neutral procedural fantasy map & world generation** — Voronoi terrain with
+hydraulic erosion, climate-driven biomes, rivers, Markov place-names, and shaded-relief
+SVG rendering. Pure Python, `numpy`-only, fully seed-deterministic.
+
+mapwright produces *neutral data* (cells, biomes, rivers, polygons) and a self-contained
+SVG renderer. It has no opinion about your application's models — map its output onto your
+own tiles/entities however you like.
+
+## Install
+
+```bash
+pip install git+https://github.com/sligara7/mapwright.git
+# or, for local development:
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from mapwright import SeededRNG, RegionalTerrainGenerator, RegionalSVGRenderer, Marker
+
+# Same seed -> same world, every time.
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(width=60, height=40)
+
+markers = [Marker(name="Eldmoor", x=30, y=18, kind="settlement_city")]
+svg = RegionalSVGRenderer().render(terrain, markers)
+open("world.svg", "w").write(svg)
+```
+
+Shape the world with `WorldMapConfig` — or describe it and let an LLM fill the config:
+
+```python
+from mapwright import WorldMapConfig, RegionalTerrainGenerator, SeededRNG
+
+desert = WorldMapConfig.preset("desert")          # ready-made worlds...
+custom = WorldMapConfig(continents=7, sea_level=0.55, temperature=-0.8)  # ...or tune
+world  = RegionalTerrainGenerator(SeededRNG(1)).generate(60, 40, config=desert)
+
+# Every field is a bounded scalar with a clear meaning, so it doubles as a schema
+# a host app (or an LLM) can populate. from_dict clamps junk to valid ranges:
+WorldMapConfig.from_dict({"temperature": 5, "continents": -3})  # -> safe, clamped
+```
+
+Presets: `continent`, `pangaea`, `archipelago`, `islands`, `highlands`, `desert`,
+`arctic`, `tropical`.
+
+Procedural place-names in several culture styles:
+
+```python
+from mapwright import SeededRNG, NameGenerator
+
+namer = NameGenerator(SeededRNG(7))
+namer.settlement("nordic")    # -> 'Eirmundheim'
+namer.settlement("elvish")    # -> 'Faelynnwood'
+namer.region("dwarvish")      # -> 'The Korvald Reach'
+```
+
+## What's inside
+
+| Component | What it does |
+|-----------|--------------|
+| `SeededRNG` | One seed drives everything; `.derive(label)` yields independent, reproducible sub-streams (unifies stdlib + numpy). |
+| `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
+| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → heightmap → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers → latitude/elevation climate → Whittaker biomes. |
+| `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, labelled markers. |
+| `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
+
+Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
+(each with a `Biome`), and you decide how a `Biome` maps to your world.
+
+## Determinism
+
+Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an
+identical world — terrain, names, rivers, and SVG — across runs *and across processes*
+(the Markov chains are built in sorted order, so output never depends on `PYTHONHASHSEED`).
+
+## API stability & contract
+
+The **public API is exactly the names exported in `mapwright.__all__`** — that's
+the contract. It's pinned by `tests/test_api_contract.py` (public surface, key
+signatures), so an accidental breaking change fails CI.
+
+For the world parameters specifically, `WorldMapConfig.json_schema()` returns a
+JSON Schema (draft 2020-12) — the machine-readable contract a host app or LLM can
+validate/generate against, then feed through `WorldMapConfig.from_dict()` (which
+clamps to valid ranges). Schema and runtime clamping are generated from the same
+field spec, so they can't drift.
+
+Versioning follows [SemVer](https://semver.org/). While at `0.x` the API may still
+change between minor versions; every change is recorded in `CHANGELOG.md`. Pin a
+tag or commit if you depend on it.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Credits & license
+
+MIT licensed (see `LICENSE`). Algorithms were implemented clean-room from the publicly
+described techniques of **Azgaar's Fantasy-Map-Generator** (MIT) and **Martin O'Leary /
+Ryan L. Guy's FantasyMapGenerator** (Zlib); see `NOTICE` for details. The bundled name
+lists are original.

mapwright-0.2.0/README.md

@@ -0,0 +1,113 @@
+# mapwright
+
+> ⚠️ **Early development (v0.1, alpha).** The API is still moving and may change without
+> notice between versions. Extracted from a working application; usable today, but pin a
+> commit if you depend on it.
+
+**Domain-neutral procedural fantasy map & world generation** — Voronoi terrain with
+hydraulic erosion, climate-driven biomes, rivers, Markov place-names, and shaded-relief
+SVG rendering. Pure Python, `numpy`-only, fully seed-deterministic.
+
+mapwright produces *neutral data* (cells, biomes, rivers, polygons) and a self-contained
+SVG renderer. It has no opinion about your application's models — map its output onto your
+own tiles/entities however you like.
+
+## Install
+
+```bash
+pip install git+https://github.com/sligara7/mapwright.git
+# or, for local development:
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from mapwright import SeededRNG, RegionalTerrainGenerator, RegionalSVGRenderer, Marker
+
+# Same seed -> same world, every time.
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(width=60, height=40)
+
+markers = [Marker(name="Eldmoor", x=30, y=18, kind="settlement_city")]
+svg = RegionalSVGRenderer().render(terrain, markers)
+open("world.svg", "w").write(svg)
+```
+
+Shape the world with `WorldMapConfig` — or describe it and let an LLM fill the config:
+
+```python
+from mapwright import WorldMapConfig, RegionalTerrainGenerator, SeededRNG
+
+desert = WorldMapConfig.preset("desert")          # ready-made worlds...
+custom = WorldMapConfig(continents=7, sea_level=0.55, temperature=-0.8)  # ...or tune
+world  = RegionalTerrainGenerator(SeededRNG(1)).generate(60, 40, config=desert)
+
+# Every field is a bounded scalar with a clear meaning, so it doubles as a schema
+# a host app (or an LLM) can populate. from_dict clamps junk to valid ranges:
+WorldMapConfig.from_dict({"temperature": 5, "continents": -3})  # -> safe, clamped
+```
+
+Presets: `continent`, `pangaea`, `archipelago`, `islands`, `highlands`, `desert`,
+`arctic`, `tropical`.
+
+Procedural place-names in several culture styles:
+
+```python
+from mapwright import SeededRNG, NameGenerator
+
+namer = NameGenerator(SeededRNG(7))
+namer.settlement("nordic")    # -> 'Eirmundheim'
+namer.settlement("elvish")    # -> 'Faelynnwood'
+namer.region("dwarvish")      # -> 'The Korvald Reach'
+```
+
+## What's inside
+
+| Component | What it does |
+|-----------|--------------|
+| `SeededRNG` | One seed drives everything; `.derive(label)` yields independent, reproducible sub-streams (unifies stdlib + numpy). |
+| `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
+| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → heightmap → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers → latitude/elevation climate → Whittaker biomes. |
+| `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, labelled markers. |
+| `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
+
+Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
+(each with a `Biome`), and you decide how a `Biome` maps to your world.
+
+## Determinism
+
+Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an
+identical world — terrain, names, rivers, and SVG — across runs *and across processes*
+(the Markov chains are built in sorted order, so output never depends on `PYTHONHASHSEED`).
+
+## API stability & contract
+
+The **public API is exactly the names exported in `mapwright.__all__`** — that's
+the contract. It's pinned by `tests/test_api_contract.py` (public surface, key
+signatures), so an accidental breaking change fails CI.
+
+For the world parameters specifically, `WorldMapConfig.json_schema()` returns a
+JSON Schema (draft 2020-12) — the machine-readable contract a host app or LLM can
+validate/generate against, then feed through `WorldMapConfig.from_dict()` (which
+clamps to valid ranges). Schema and runtime clamping are generated from the same
+field spec, so they can't drift.
+
+Versioning follows [SemVer](https://semver.org/). While at `0.x` the API may still
+change between minor versions; every change is recorded in `CHANGELOG.md`. Pin a
+tag or commit if you depend on it.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Credits & license
+
+MIT licensed (see `LICENSE`). Algorithms were implemented clean-room from the publicly
+described techniques of **Azgaar's Fantasy-Map-Generator** (MIT) and **Martin O'Leary /
+Ryan L. Guy's FantasyMapGenerator** (Zlib); see `NOTICE` for details. The bundled name
+lists are original.

mapwright-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mapwright"
+version = "0.2.0"
+description = "Domain-neutral procedural fantasy map & world generation: Voronoi terrain, hydraulic erosion, biomes, rivers, Markov place-names, and shaded-relief SVG."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Anthony Sligar" }]
+keywords = [
+    "procedural-generation",
+    "fantasy-map",
+    "worldgen",
+    "voronoi",
+    "terrain",
+    "erosion",
+    "biomes",
+    "ttrpg",
+    "svg",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Multimedia :: Graphics",
+    "Topic :: Games/Entertainment :: Role-Playing",
+]
+dependencies = ["numpy>=1.26"]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.4", "ruff>=0.1"]
+
+[project.urls]
+Homepage = "https://github.com/sligara7/mapwright"
+Repository = "https://github.com/sligara7/mapwright"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mapwright"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"

mapwright-0.2.0/src/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",
+]