mapwright 0.16.0__tar.gz → 0.18.0__tar.gz

{mapwright-0.16.0 → mapwright-0.18.0}/CHANGELOG.md

@@ -8,6 +8,48 @@ All notable changes to mapwright are documented here. The format follows
 `tests/test_api_contract.py`). While the version is `0.x`, minor versions may
 make breaking changes; these will always be noted here.
 
+## [0.18.0] — 2026-06-02
+
+### Added
+- **Environmental affordances + cell aggregation — `affordances` module.** Two
+  domain-neutral helpers for turning terrain into a place's *environment*:
+  - `environment_affordances(biome, temperature, moisture)` → neutral
+    ecology-level tags (`scarce_water`, `disease_vector`, `predator`,
+    `extreme_heat`, …). Biome-base tags plus climate-driven additions, so a
+    hot+wet forest reads as a steamy jungle. A host app decides what, if
+    anything, tags mean mechanically; this library never touches game rules.
+  - `summarize_cells(cells)` → `CellSummary` (dominant biome, mean climate,
+    hydrology flags, water fraction, affordances) for a footprint / explored
+    area / whole map. Deterministic; ties broken by lowest `Biome` value.
+  - New exports: `environment_affordances`, `summarize_cells`, `CellSummary`
+    (purely additive to `__all__`).
+- **Themes extended to the town & dungeon renderers.** A `Theme` now carries
+  nested `SettlementPalette` + `DungeonPalette` sub-palettes, and
+  `SettlementSVGRenderer` / `DungeonSVGRenderer` take a `theme=` just like the
+  regional renderer — so one theme skins all three. The four built-ins
+  (`parchment`, `neon`, `dune`, `blueprint`) now style towns and dungeons
+  cohesively (e.g. a neon citadel, a blueprint dungeon). Sub-palettes default to
+  parchment, so a theme that only restyles the regional map still drives the
+  other renderers, and the default output is **byte-identical**. `SettlementPalette`
+  / `DungeonPalette` are importable from `mapwright.themes` for authoring custom
+  themes. Gallery gains a themed town + dungeon.
+
+## [0.17.0] — 2026-06-02
+
+### Added
+- **Render themes — `Theme` + `THEMES`.** `RegionalSVGRenderer` now takes a
+  `theme=` (a name or a `Theme`): a palette plus an optional biome *vocabulary*
+  that re-skins the same neutral terrain without regenerating anything. The
+  `Biome` enum is unchanged — a theme only decides how each biome looks and is
+  named — so this is purely additive and the contract is stable. Built-ins:
+  `parchment` (default, **byte-identical** to the previous output), `neon`
+  (Tron / digital-grid), `dune` (Tatooine / sand medium), and `blueprint`.
+  `Theme` is plain hex-string data (JSON-friendly), so a host or image service
+  can author new ones; `Theme.biome_label()` exposes the vocabulary (e.g.
+  `OCEAN` → "Void"). This is the first slice of the "Dominant Medium" /
+  render-theme direction — pair a theme with a matching `ArtPack` for a full
+  restyle. Gallery gains a same-continent neon/dune/blueprint showcase.
+
 ## [0.16.0] — 2026-06-02
 
 ### Added

{mapwright-0.16.0 → mapwright-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapwright
-Version: 0.16.0
+Version: 0.18.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
@@ -41,7 +41,36 @@ own tiles/entities however you like.
 
 ## Gallery
 
-Every image below is a deterministic render of a built-in preset (or a dungeon),
+**`AtlasRenderer`** — the same neutral terrain, skinned with a hand-drawn *art pack*.
+The art here is original, generated through mapwright's companion image service and
+stamped where the physics put it (mountains on the ranges, forests by climate, sea
+serpents offshore). mapwright itself ships no art — the pack is the skin:
+
+<p align="center">
+<img width="640" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/atlas.png" alt="hand-drawn atlas rendered from a sample art pack">
+</p>
+
+**Render themes** — the *same* continent (same cells, rivers, roads, settlements),
+re-skinned by swapping a `Theme` (palette + biome vocabulary). No regeneration:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-neon.png" alt="neon (Tron) theme"><br><sub><code>theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dune.png" alt="dune (sand) theme"><br><sub><code>theme="dune"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-blueprint.png" alt="blueprint theme"><br><sub><code>theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+The same `theme=` drives the **town and dungeon** renderers too — one skin across all three:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-citadel-neon.png" alt="neon-themed walled citadel"><br><sub><code>Settlement, theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dungeon-blueprint.png" alt="blueprint-themed dungeon"><br><sub><code>Dungeon, theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+Below: deterministic shaded-relief renders of each built-in preset (or a dungeon),
 produced by [`examples/gallery.py`](examples/gallery.py):
 
 <table>
@@ -197,14 +226,16 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 | `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
 | `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → **tectonic-plate** heightmap (organic coasts + mountain ranges at plate collisions; percentile sea level) → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
 | `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
-| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. Takes a `theme=`. |
+| `Theme` / `THEMES` | A render palette + biome vocabulary; re-skins the same terrain — and its towns and dungeons — via one `theme=` (parchment / neon / dune / blueprint, or your own). The "Dominant Medium" layer. |
+| `environment_affordances` / `summarize_cells` | Neutral *ecology* helpers: biome + climate → affordance tags (`scarce_water`, `predator`, …); reduce a set of cells to a `CellSummary` (dominant biome, mean climate, hydrology, affordances). A host decides what tags mean mechanically. |
 | `AtlasRenderer` / `ArtPack` | Hand-drawn / themed PNG: stamps symbols from an external *art pack* (mountains, forests, hills, settlements, sea decorations) onto the terrain. mapwright ships no art — a pack is a skin. Needs `pip install "mapwright[atlas]"`. |
 | `RegionalRoadGenerator` | Connects settlement sites with trade routes — an MST whose edges are A*-routed over the terrain (avoids sea, climbs/crosses rivers at a cost). |
 | `RegionGenerator` | Partitions land into named factions/territories: spread capitals seed a flood fill over the land graph (sea divides them); each `Region` is Markov-named. |
 | `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
-| `DungeonSVGRenderer` | Renders a `Dungeon` to SVG: walls, carved floor, room outlines, optional tile grid and per-room labels. |
+| `DungeonSVGRenderer` | Renders a `Dungeon` to SVG: walls, carved floor, room outlines, optional tile grid and per-room labels. Takes a `theme=`. |
 | `SettlementGenerator` | Self-contained town layout: an organic footprint divided into named Voronoi **wards** (market, docks, …), each subdivided into building **lots**, a **street** network (MST over ward adjacency + main roads from gates to the market), an optional defensive **wall** (towers + gate gaps, opened at the harbour when coastal), and optional coastline. |
-| `SettlementSVGRenderer` | Renders a `Settlement` to SVG: sea, footprint, kind-coloured wards, building lots, streets, wall with towers/gatehouses, labels. |
+| `SettlementSVGRenderer` | Renders a `Settlement` to SVG: sea, footprint, kind-coloured wards, building lots, streets, wall with towers/gatehouses, labels. Takes a `theme=`. |
 
 Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
 (each with a `Biome`), and you decide how a `Biome` maps to your world.
@@ -259,6 +290,32 @@ sibling (`mountain.mid` → any `mountain.*`), so partial packs still render. Wi
 folder layout. Because packs are pure data, a host like an image-generation service can
 **produce them on demand** in any style — the generation stays the same; the pack is the skin.
 
+### Render themes
+
+The vector `RegionalSVGRenderer` takes a **`Theme`** — a palette plus an optional biome
+*vocabulary* — so the same neutral terrain re-skins into wildly different worlds without
+regenerating anything. The neutral `Biome` enum never changes; a theme just decides how
+each biome looks and is named:
+
+```python
+from mapwright import RegionalSVGRenderer, SettlementSVGRenderer, DungeonSVGRenderer, THEMES
+
+svg  = RegionalSVGRenderer(theme="neon").render(terrain, markers, roads=roads)
+town = SettlementSVGRenderer(theme="neon").render(settlement)   # same theme skins the town
+dgn  = DungeonSVGRenderer(theme="blueprint").render(dungeon)    # …and the dungeon
+# built-ins: "parchment" (default), "neon" (Tron/digital-grid), "dune" (sand), "blueprint"
+THEMES["neon"].biome_label(Biome.OCEAN)   # -> "Void"  (the vocabulary layer)
+```
+
+All three renderers take the same `theme=`, so one theme skins the world map, its towns,
+and its dungeons together (a `Theme` carries nested `SettlementPalette` + `DungeonPalette`,
+importable from `mapwright.themes` for custom packs). A `Theme` is plain hex-string data
+(JSON-friendly), so a host — or the same image service that makes art packs — can author
+new ones. This is the "Dominant Medium" idea from mapwright's longer-term vision: a sand
+planet, a digital grid, and an irradiated waste are the *same map* wearing different skins.
+Pair a theme with a matching `ArtPack` for a full restyle of both the vector and hand-drawn
+renders.
+
 ## Determinism
 
 Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an

{mapwright-0.16.0 → mapwright-0.18.0}/README.md

@@ -14,7 +14,36 @@ own tiles/entities however you like.
 
 ## Gallery
 
-Every image below is a deterministic render of a built-in preset (or a dungeon),
+**`AtlasRenderer`** — the same neutral terrain, skinned with a hand-drawn *art pack*.
+The art here is original, generated through mapwright's companion image service and
+stamped where the physics put it (mountains on the ranges, forests by climate, sea
+serpents offshore). mapwright itself ships no art — the pack is the skin:
+
+<p align="center">
+<img width="640" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/atlas.png" alt="hand-drawn atlas rendered from a sample art pack">
+</p>
+
+**Render themes** — the *same* continent (same cells, rivers, roads, settlements),
+re-skinned by swapping a `Theme` (palette + biome vocabulary). No regeneration:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-neon.png" alt="neon (Tron) theme"><br><sub><code>theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dune.png" alt="dune (sand) theme"><br><sub><code>theme="dune"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-blueprint.png" alt="blueprint theme"><br><sub><code>theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+The same `theme=` drives the **town and dungeon** renderers too — one skin across all three:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-citadel-neon.png" alt="neon-themed walled citadel"><br><sub><code>Settlement, theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dungeon-blueprint.png" alt="blueprint-themed dungeon"><br><sub><code>Dungeon, theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+Below: deterministic shaded-relief renders of each built-in preset (or a dungeon),
 produced by [`examples/gallery.py`](examples/gallery.py):
 
 <table>
@@ -170,14 +199,16 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 | `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
 | `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → **tectonic-plate** heightmap (organic coasts + mountain ranges at plate collisions; percentile sea level) → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
 | `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
-| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. Takes a `theme=`. |
+| `Theme` / `THEMES` | A render palette + biome vocabulary; re-skins the same terrain — and its towns and dungeons — via one `theme=` (parchment / neon / dune / blueprint, or your own). The "Dominant Medium" layer. |
+| `environment_affordances` / `summarize_cells` | Neutral *ecology* helpers: biome + climate → affordance tags (`scarce_water`, `predator`, …); reduce a set of cells to a `CellSummary` (dominant biome, mean climate, hydrology, affordances). A host decides what tags mean mechanically. |
 | `AtlasRenderer` / `ArtPack` | Hand-drawn / themed PNG: stamps symbols from an external *art pack* (mountains, forests, hills, settlements, sea decorations) onto the terrain. mapwright ships no art — a pack is a skin. Needs `pip install "mapwright[atlas]"`. |
 | `RegionalRoadGenerator` | Connects settlement sites with trade routes — an MST whose edges are A*-routed over the terrain (avoids sea, climbs/crosses rivers at a cost). |
 | `RegionGenerator` | Partitions land into named factions/territories: spread capitals seed a flood fill over the land graph (sea divides them); each `Region` is Markov-named. |
 | `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
-| `DungeonSVGRenderer` | Renders a `Dungeon` to SVG: walls, carved floor, room outlines, optional tile grid and per-room labels. |
+| `DungeonSVGRenderer` | Renders a `Dungeon` to SVG: walls, carved floor, room outlines, optional tile grid and per-room labels. Takes a `theme=`. |
 | `SettlementGenerator` | Self-contained town layout: an organic footprint divided into named Voronoi **wards** (market, docks, …), each subdivided into building **lots**, a **street** network (MST over ward adjacency + main roads from gates to the market), an optional defensive **wall** (towers + gate gaps, opened at the harbour when coastal), and optional coastline. |
-| `SettlementSVGRenderer` | Renders a `Settlement` to SVG: sea, footprint, kind-coloured wards, building lots, streets, wall with towers/gatehouses, labels. |
+| `SettlementSVGRenderer` | Renders a `Settlement` to SVG: sea, footprint, kind-coloured wards, building lots, streets, wall with towers/gatehouses, labels. Takes a `theme=`. |
 
 Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
 (each with a `Biome`), and you decide how a `Biome` maps to your world.
@@ -232,6 +263,32 @@ sibling (`mountain.mid` → any `mountain.*`), so partial packs still render. Wi
 folder layout. Because packs are pure data, a host like an image-generation service can
 **produce them on demand** in any style — the generation stays the same; the pack is the skin.
 
+### Render themes
+
+The vector `RegionalSVGRenderer` takes a **`Theme`** — a palette plus an optional biome
+*vocabulary* — so the same neutral terrain re-skins into wildly different worlds without
+regenerating anything. The neutral `Biome` enum never changes; a theme just decides how
+each biome looks and is named:
+
+```python
+from mapwright import RegionalSVGRenderer, SettlementSVGRenderer, DungeonSVGRenderer, THEMES
+
+svg  = RegionalSVGRenderer(theme="neon").render(terrain, markers, roads=roads)
+town = SettlementSVGRenderer(theme="neon").render(settlement)   # same theme skins the town
+dgn  = DungeonSVGRenderer(theme="blueprint").render(dungeon)    # …and the dungeon
+# built-ins: "parchment" (default), "neon" (Tron/digital-grid), "dune" (sand), "blueprint"
+THEMES["neon"].biome_label(Biome.OCEAN)   # -> "Void"  (the vocabulary layer)
+```
+
+All three renderers take the same `theme=`, so one theme skins the world map, its towns,
+and its dungeons together (a `Theme` carries nested `SettlementPalette` + `DungeonPalette`,
+importable from `mapwright.themes` for custom packs). A `Theme` is plain hex-string data
+(JSON-friendly), so a host — or the same image service that makes art packs — can author
+new ones. This is the "Dominant Medium" idea from mapwright's longer-term vision: a sand
+planet, a digital grid, and an irradiated waste are the *same map* wearing different skins.
+Pair a theme with a matching `ArtPack` for a full restyle of both the vector and hand-drawn
+renders.
+
 ## Determinism
 
 Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an

mapwright-0.18.0/docs/gallery/atlas_pack/README.md

@@ -0,0 +1,17 @@
+# Sample art pack (`atlas_pack`)
+
+A small **example** art pack for `AtlasRenderer`, used only to render the
+hand-drawn atlas thumbnail in the project README (`docs/gallery/atlas.png`,
+produced by `examples/gallery.py`).
+
+- **Provenance:** the symbols were generated by an OpenRouter image model through
+  mapwright's companion service (storyflow `media_service`), via
+  `scripts/gen_mapwright_pack.py` there. They are original, model-generated art —
+  not copied from any third-party asset set.
+- **Scope:** this pack lives under `docs/` and is **not** shipped in the PyPI
+  wheel (which packages `src/mapwright/` only). mapwright ships no art; this is a
+  demo skin.
+- **Layout:** `manifest.json` maps mapwright's neutral slots
+  (`mountain.young`, `tree.pine`, `city.castle`, …) to the PNG variants here.
+  See the *Atlas rendering & art packs* section of the top-level README for the
+  schema.

mapwright-0.18.0/docs/gallery/atlas_pack/manifest.json

@@ -0,0 +1,122 @@
+{
+  "name": "atlas_pack",
+  "style": "antique-ink",
+  "colors": {
+    "parchment": "#ecdfbf",
+    "water": "#a9c2cc",
+    "coast": "#463c2c",
+    "label": "#2b2218"
+  },
+  "slots": {
+    "mountain.young": {
+      "files": [
+        "mountain_young_1.png",
+        "mountain_young_2.png"
+      ],
+      "width": 2.0,
+      "anchor": "bottom"
+    },
+    "mountain.mid": {
+      "files": [
+        "mountain_mid_1.png"
+      ],
+      "width": 2.0,
+      "anchor": "bottom"
+    },
+    "mountain.old": {
+      "files": [
+        "mountain_old_1.png",
+        "mountain_old_2.png"
+      ],
+      "width": 2.0,
+      "anchor": "bottom"
+    },
+    "hill": {
+      "files": [
+        "hill_1.png",
+        "hill_2.png"
+      ],
+      "width": 1.5,
+      "anchor": "bottom"
+    },
+    "tree.pine": {
+      "files": [
+        "tree_pine_1.png",
+        "tree_pine_2.png"
+      ],
+      "width": 1.0,
+      "anchor": "bottom"
+    },
+    "tree.deciduous": {
+      "files": [
+        "tree_deciduous_1.png",
+        "tree_deciduous_2.png"
+      ],
+      "width": 1.0,
+      "anchor": "bottom"
+    },
+    "tree.cactus": {
+      "files": [
+        "tree_cactus_1.png"
+      ],
+      "width": 1.0,
+      "anchor": "bottom"
+    },
+    "dune": {
+      "files": [
+        "dune_1.png"
+      ],
+      "width": 0.9,
+      "anchor": "bottom"
+    },
+    "city.castle": {
+      "files": [
+        "city_castle_1.png"
+      ],
+      "width": 1.7,
+      "anchor": "bottom"
+    },
+    "city.large": {
+      "files": [
+        "city_large_1.png"
+      ],
+      "width": 1.7,
+      "anchor": "bottom"
+    },
+    "city.town": {
+      "files": [
+        "city_town_1.png"
+      ],
+      "width": 1.7,
+      "anchor": "bottom"
+    },
+    "city.village": {
+      "files": [
+        "city_village_1.png"
+      ],
+      "width": 1.7,
+      "anchor": "bottom"
+    },
+    "decoration.compass": {
+      "files": [
+        "decoration_compass_1.png"
+      ],
+      "width": 3.0,
+      "anchor": "center"
+    },
+    "decoration.ship": {
+      "files": [
+        "decoration_ship_1.png"
+      ],
+      "width": 3.0,
+      "anchor": "center"
+    },
+    "decoration.creature": {
+      "files": [
+        "decoration_creature_1.png"
+      ],
+      "width": 3.0,
+      "anchor": "center"
+    }
+  }
+}