Skip to content

Generate Places

m4bwav edited this page Nov 16, 2026 · 7 revisions

Towns, dungeons and battle maps for tabletop and game use. Each is a recipe folder like a world (Recipe format), checked by proof bars, drawn by render in ink-and-parchment or blueprint, and exported to Universal VTT or Tiled (Export). All take --seed, --out, --style and --name-style (a sound pattern from names --list).

gen city

Rings and gate roads grown from a market, blocks cut into lots that each keep street frontage, buildings, a wall with gates, and named districts. Options: --bands (rings of blocks), --wall (the ring the wall stands on), --no-walls, --spokes (gate roads, 5 to 7 by seed), --ring-m, --lot-m2, --sea and --river (directions in radians, 0 east, pi/2 south). --parent WORLD sites the city on a world's settlement (--settlement ID, default the top-scored one) and takes its name, language, coast and river.

python scripts/mpw.py gen city --seed 4 --out town.map
wrote town.map: Ewakake, 114 streets, 49 blocks, 1047 lots, 15 districts, 5 gates, 0 bridges in 0.14 s
python scripts/mpw.py check town.map
bar 1 PASS: city: every street reachable from the market (364 of 364 street nodes reached)
bar 2 PASS: city: every block fronts a reached street (49 blocks, 0 without a reached street edge)
bar 3 PASS: city: lots simple, positive and inside their block (1047 lots, 0 bad)
bar 4 PASS: city: every built lot has street frontage (1047 lots, 0 without frontage (left as yards, never built on), 0 built without frontage)
bar 5 PASS: city: gates on the wall, streets cross it only at gates (5 gates (0 off the wall), 0 streets cut the wall, 0 leave it without a gate; wall closed)
bar 6 PASS: same seed gives byte-identical files (5 files identical)
bar 7 PASS: labels: none overlap (16 labels, 0 overlapping pairs)
bar 8 PASS: labels: none cut by the edge (0 cut)
bar 9 SKIP: labels: read back by OCR (skipped: tesseract not found (install it to run this bar))

The ward plan follows Watabou's Medieval Fantasy City Generator, reimplemented rather than copied.

gen dungeon

Four methods, all on a square grid at a whole number of pixels per square (--w, --h in squares, --pps):

  • bsp (default): rooms split by binary space partition, joined with loops, doors and lights.
  • cave: cellular automaton caves. The rules are flags kept in the recipe: --fill (0.45), --passes (5), --birth (5), --survival (4), --radius 1|2, --border (1).
  • cyclic: a lock-and-key graph first (two paths from start to goal, nested cycles, one-way doors), raised to the same grid as bsp, so render, export and check work on it.
  • blocks (since 0.13.0): an exit-matched grid of 7x7-square blocks grown from a start slot, so every exit inside the map meets an exit on its neighbour; open edges merge into one-square halls, about 70 percent of blocks hold a room and the rest are hall junctions. It places no doors. The bar is 40 blocks on a 7x7 grid, scaled to the map's grid and rounded up (25 of 6x5 at 48x36); the map must be at least 21x21 squares. A grid under the bar, or a path shorter than the map width, is grown again, up to 32 restarts, counted in recipe.json blocks.rerolls. check adds two bars for it (see below).

Wide corridors (since 0.21.0)

--corridor N (bsp only, 1 to 3) carves corridors N squares wide; above 1 the room openings are left as open gaps with no doors, so a body N squares wide can leave every room. It is stored in the recipe, so check regenerates the same map; --corridor 1 (the default) gives the same files as before. From a real run on v0.21.0:

$ mpw.py gen dungeon --seed 3 --w 40 --h 30 --corridor 2 --out d3c2
wrote d3c2: Koda, 40x30 square squares at 70 px, 7 rooms, 0 doors, 52 wall runs, 7 lights in 0.06 s
$ mpw.py path d3c2 --from 2,2 --to 30,20 --agent 2 --out o3
path: cost 42.9706 steps, 38 steps, 195 cells expanded -> o3

The same route fails on the default map (see Paths and travel). Over 100 seeds a 2-wide body reached every room on 0 maps at --corridor 1 and on 100 at --corridor 2. Since 0.22.0 cyclic takes it too: each edge is an open gap N squares wide that keeps its lock or one-way flag on every gap square (a 2-wide body reaches every room on 100 of 100 seeds at --corridor 2). Since 0.23.0 blocks takes it too: its halls and hub widen to N squares (a 2-wide body reaches every room on 97 of 100 seeds at --corridor 2, a 3-wide body on 84 of 100 at --corridor 3; from a real run, gen dungeon --method blocks --seed 3 --w 40 --h 30 --corridor 2 writes 10 rooms, 0 doors and passes check). cave does not take it.

Since 0.9.0 every dungeon has an entrance and a goal, drawn on the map and written to grid.json and features.geojson. bsp and cave put the goal on the floor square farthest from the entrance, and the path between them is at least the map width (a shorter map is re-rolled, at most 16 times; the count is stored).

blocks on seed 3 (checked by hand on v0.13.0; check prints 19 bars, all PASS apart from the OCR SKIP; the two blocks bars are shown):

python scripts/mpw.py gen dungeon --seed 3 --method blocks --out blocks.map
python scripts/mpw.py check blocks.map
wrote blocks.map: Koda, 48x36 square squares at 70 px, 24 rooms, 0 doors, 178 wall runs, 24 lights in 0.10 s
bar 6 PASS: blocks: no unmatched exit inside the map, none off the edge, squares match the flags (0 unmatched, 0 off the edge, 0 squares disagree)
bar 7 PASS: blocks: at least 25 blocks placed (40 of 49, scaled to 6x5) (29 placed after 0 restarts)
python scripts/mpw.py gen dungeon --seed 3 --method bsp --out crypt.map
python scripts/mpw.py gen dungeon --seed 3 --method cave --out cave.map
python scripts/mpw.py gen dungeon --seed 3 --method cyclic --out keep.map
wrote crypt.map: Koda, 48x36 square squares at 70 px, 14 rooms, 19 doors, 96 wall runs, 14 lights in 0.08 s
wrote cave.map: Koda, 48x36 square squares at 70 px, 0 rooms, 0 doors, 174 wall runs, 9 lights in 0.08 s
wrote keep.map: Koda, 48x36 square squares at 70 px, 20 rooms, 24 doors, 144 wall runs, 20 lights in 0.08 s
python scripts/mpw.py check crypt.map
bar 1 PASS: dungeon: every floor square reachable from the entrance (854 of 854 passable squares reached)
bar 2 PASS: dungeon: every room reached, none overlap (14 rooms, 0 unreached, 0 overlapping pairs)
bar 3 PASS: dungeon: goal at the floor square farthest from the entrance (goal 108 steps, map maximum 108)
bar 4 PASS: dungeon: entrance-to-goal path at least 48 steps (map width) (shortest path 108 steps)
bar 5 PASS: dungeon: no isolated wall squares (every wall has two wall neighbours) (0 isolated, 51% of squares wall)
bar 6 PASS: dungeon: every door reached and joins two floors (19 doors, 0 bad)
bar 7 PASS: dungeon: walls closed (every wall end meets another) (96 wall runs, 0 loose ends)
bar 8 PASS: dungeon: grid on whole pixels (map.png 3360x2520 = 48x36 squares x 70 px)
bar 9 PASS: uvtt: loads, pixels_per_grid a whole number (ppg 70, 96 walls, 19 portals, 14 lights)
bar 10 PASS: uvtt: walls inside the image (96 walls, 0 points outside 48x36)
bar 11 PASS: uvtt: every door ends on a wall (0 door ends off a wall)
bar 12 PASS: uvtt: image matches the grid (3360x2520 px for 48x36 squares at 70)
bar 13 PASS: uvtt: colours alpha first, doors closed, no wall over a door (0 colours not ffRRGGBB, 0 portals not closed, 0 doors under a wall)
bar 14 PASS: same seed gives byte-identical files (7 files identical)
bar 15 PASS: labels: none overlap (15 labels, 0 overlapping pairs)
bar 16 PASS: labels: none cut by the edge (0 cut)
bar 17 SKIP: labels: read back by OCR (skipped: tesseract not found (install it to run this bar))

On a cyclic dungeon check adds cycle rank, adjacency, key before lock, the lock as a gate on the squares, and a return path. The seed is the same for all three methods above, and so is the name: names come from the seed, not the layout.

Expressive range

check --range METHOD generates many seeds (--seeds, default 500; --w, --h) and measures how varied they are, writing range.json and range.svg (a heatmap). The metrics are mapwright's own: dead-end share counts parts joined by one bridge, loop share counts corridor squares on a loop.

python scripts/mpw.py check --range bsp --seeds 20
expressive range: gen dungeon --method bsp, 20 seeds, 48x36 -> range-bsp
  loop_share          min 0.300  mean 0.585  max 0.872
  dead_end_share      min 0.109  mean 0.355  max 0.899
  path_over_diagonal  min 1.100  mean 1.614  max 2.117
  open_floor_share    min 0.420  mean 0.476  max 0.552
  loop_share x dead_end_share: 17 of 100 bins used, fullest bin 15.0%, first 10 seeds against all 20 TV 0.450
  path_over_diagonal x open_floor_share: 18 of 100 bins used, fullest bin 15.0%, first 10 seeds against all 20 TV 0.450

The last number is the total variation between the first half of the seeds and all of them; with 20 seeds it is large, which is the point of the default 500.

Side branches (since 0.11.0)

--branches N (0 to 8) adds dead-end side rooms to a cyclic dungeon, with treasure and secret doors and never a key. Without the flag a seed gives the same dungeon as 0.10.

python scripts/mpw.py gen dungeon --seed 3 --method cyclic --branches 3 --out wings.map
python scripts/mpw.py check wings.map
wrote wings.map: Koda, 48x36 square squares at 70 px, 24 rooms, 28 doors, 174 wall runs, 24 lights in 0.09 s
bar 7 PASS: cyclic: every key reached before its lock, every room reached, the lock is a real gate (1 locks, keys taken in order k1, 24 of 24 rooms reached, goal not reached without the key)

check prints 12 bars on this map, all PASS; the key bar is shown. Bar 3 reports the shortest entrance-to-goal path as 134 steps, fetching the key first.

gen battle

A square or hex battle map (--grid square|hex), --w and --h in squares or hexes, --pps pixels per square (for hex, the hex width, even). --density sparse|normal|dense (since 0.11.0) sets the share of cells holding a feature: normal is the default, sparse is the map 0.10 and older made.

python scripts/mpw.py gen battle --seed 2 --grid square --out field.map
python scripts/mpw.py gen battle --seed 2 --grid hex --out hexes.map
wrote field.map: Ninbuqaa, 30x20 square squares at 100 px, 0 rooms, 3 doors, 52 wall runs, 5 lights in 0.08 s
wrote hexes.map: Ninbuqaa, 30x20 hex squares at 100 px, 0 rooms, 0 doors, 0 wall runs, 0 lights in 0.03 s
python scripts/mpw.py gen battle --seed 2 --grid square --density sparse --out sparse.map
python scripts/mpw.py gen battle --seed 2 --grid square --density dense --out dense.map
wrote sparse.map: Ninbuqaa, 30x20 square squares at 100 px, 0 rooms, 3 doors, 48 wall runs, 5 lights in 0.20 s
wrote dense.map: Ninbuqaa, 30x20 square squares at 100 px, 0 rooms, 3 doors, 52 wall runs, 5 lights in 0.09 s

Since 0.11.0 the legend in map.svg lists only the kinds of feature on the map. On these three maps all three kinds are there: rock or ruined wall (blocks), trees (block movement, cover), doorway or gap. Since 0.12.0 the title sits in a band above the grid and the legend in a band below it, so neither hides a square. legend lists the same entries for a battle map (rock, tree, door on seed 3); on a city or dungeon map it says there is no legend.

Hex maps export to PNG only: Universal VTT has no hex walls, and there is no Tiled export for hexes yet.

Render

python scripts/mpw.py render crypt.map -o crypt.svg --style blueprint --title "The Crypt"
wrote crypt.svg

--title names city, dungeon and battle maps since 0.10.1.

Clone this wiki locally