Repository navigation
Generate Worlds
A world is a recipe folder: plates, erosion, rivers, lakes, climate, biomes, settlements, roads and names over a 1000 km square. A region is a child map inside a window of a world that keeps its parent's coast, rivers, settlements, roads and names. Files: Recipe format. Other kinds: Generate places, Generate space.
gen world also takes --plates, --erosion (stream-power steps, 10 to 20), --lat-top and --lat-bottom (default 60 and 0) and --raster (heights.png width). gen region takes --detail (detail noise amplitude) and --raster.
A new world as a recipe folder. Options: --seed N, --cells (default 16000), --style S or --pattern P for the names, --out DIR.
python scripts/mpw.py gen world --seed 7 --style nordic --out isles.mapwrote isles.map: 15876 cells, 48 rivers, 22 lakes, 81 settlements, 94 roads, 162 names in 1.36 s
A child map inside a window of the parent, in map km (0 to 1000, y south). zoom DIR --out DIR picks the coast-richest quarter for you. The child stores its parent's path relative to itself, so move the two folders together.
python scripts/mpw.py gen region --parent isles.map --window 100,100,400,350 --cells 8000 --out isles-west.mapwrote isles-west.map: 8036 cells, 32 rivers, 21 lakes, 31 settlements, 33 roads, 88 names in 0.83 s
python scripts/mpw.py zoom isles.map --out isles-south.mapwrote isles-south.map: 16002 cells, 8 rivers, 3 lakes, 21 settlements, 27 roads, 37 names in 1.44 s
gen region --chunk COL,ROW takes chunk COL,ROW of a grid of --chunk-km squares (default 250 km) as the window, instead of --window. Its detail seed comes from the world seed and the chunk (place_seed(world_seed, "region", "col,row@km")) and is recorded under place, so one chunk can be made again alone, byte-identical, and check regenerates it. Coast and rivers still come from the parent. From a real run on v0.19.0 (seed 7 world):
python scripts/mpw.py gen region --parent isles.map --chunk 1,2 --out chunk-1-2.mapwrote chunk-1-2.map: 16002 cells, 11 rivers, 17 lakes, 18 settlements, 23 roads, 51 names in 1.18 s
recipe.json then holds "place": {"world_seed": 7, "chunk": [1, 2], "chunk_km": 250.0}.
Runs the land bars and the label bars on a recipe folder and exits 1 on any failure. --no-regen skips the regeneration bars, --no-labels the label bars. Each bar is explained on Proof bars.
python scripts/mpw.py check isles-south.mapbar 1 PASS: every river runs downhill to the sea or through a lake to it (42 river cells, 0 failures)
bar 2 PASS: no river splits outside a marked delta (0 splits, 0 rivers that stop on land, 0 marked deltas)
bar 3 PASS: each lake has at most one outlet (3 lakes, max outlets 1)
bar 4 PASS: same recipe gives byte-identical files (all 8 files identical)
bar 5 PASS: child coast within 1 parent spacing of the parent coast (875 child coast segments, max 0.679, mean 0.177 parent spacings)
bar 6 PASS: parent rivers present in the child within 1 parent spacing (4 parent river points, max 0.128 parent spacings)
bar 7 PASS: climate: temperature falls poleward; lee of mountains drier (sea-level temp by 10-deg band 25.9/22.7; windward 0 vs leeward 32 cm/yr (too few samples, shadow not judged))
bar 8 PASS: every settlement on land and not in a lake (21 settlements, 0 in water)
bar 9 PASS: all settlements of one landmass connected by roads (3 landmasses with settlements, 0 split)
bar 10 PASS: roads never run through sea or lake cells (no ferries) and step cell to cell (27 roads, 758 road cells, 0 in water, 0 jumps)
bar 11 PASS: names unique and present for every named feature (37 names, 0 duplicates, 0 features unnamed, 0 feature names missing from names.json)
bar 12 PASS: same seed gives byte-identical names.json and features.geojson (identical)
bar 13 PASS: child keeps parent settlements and roads within 1 parent + 1 child spacing (8 parent settlements in window, 0 missing or renamed, max shift 1.42 km; 141 parent road points, max 1.43 km; tolerance 9.91 km)
bar 14 PASS: every port touches open sea (a lakeshore town is never a port), at most 25% of settlements (6 ports (cap 6), 0 off open sea)
bar 15 PASS: labels: none overlap (23 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))
Same seed, same files: two runs of gen world --seed 7 give byte-identical features.geojson (cmp prints nothing), and the 0.2.0 counts above are unchanged in 0.11.0.
Next: render the folder, export it to an engine or a print, or route across it with path and travel.
This wiki describes mapwright 0.24.0 (released 2026-11-16) and was last updated on 2026-11-16. mapwright is MIT licensed. Report problems in the issues.