Skip to content
m4bwav edited this page Nov 16, 2026 · 3 revisions

export RECIPE -o FILE writes a recipe to the tools that take a map further. --to TARGET picks the target; without it the extension does (.dd2vtt, .tmj, .raw, .r16, .obj, .pdf, .tab, and .png for a planet or hex map). Every writer reads its own file back and prints proof bars before it reports the file.

Target From Writes
uvtt dungeon, square battle map, deck plan Universal VTT (.dd2vtt) for Foundry and other tabletops; one file per deck
tiled dungeon, square battle map, deck plan a Tiled map (.tmj) and its tile image
png hex battle map a PNG at the SVG's size
nav dungeon, square battle map walkable rectangles and portals as JSON (since 0.11.0)
unity world, region 16-bit RAW heightmap, 2^n + 1 square
unreal world, region 16-bit PNG heightmap (1009 and kin)
godot world, region .r16 (preferred) or 16-bit PNG
roblox world, region heightmap PNG plus a material colormap
mesh world, region terrain .obj plus a polywright manifest
print world, region PDF and PNG at a paper size, with bleed and crop marks
sphere planet the texture as a sphere PNG plus a hand-off note
t5 sector the T5 tab-delimited file

Heightmaps also write an .import.json sidecar with the height scale: the lowest to the highest height is stretched over the full range.

Universal VTT and Tiled

python scripts/mpw.py export crypt.map -o crypt.dd2vtt
PASS: uvtt: loads, pixels_per_grid a whole number (ppg 70, 96 walls, 19 portals, 14 lights)
PASS: uvtt: walls inside the image (96 walls, 0 points outside 48x36)
PASS: uvtt: every door ends on a wall (0 door ends off a wall)
PASS: uvtt: image matches the grid (3360x2520 px for 48x36 squares at 70)
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)
wrote crypt.dd2vtt
python scripts/mpw.py export crypt.map -o crypt.tmj
PASS: tiled: parses, one tile layer per level (1 tile layer(s), 2 object layer(s), version 1.10)
PASS: tiled: layer size equals the recipe grid (48 x 36 tiles of 32 px)
PASS: tiled: every gid is a tile in the tileset image (0 gids outside 1..6, image 192 x 32 for 6 tiles)
PASS: tiled: floor cells equal the recipe's (835 floor cells, recipe 835, 0 cells differ)
PASS: tiled: wall and door objects inside the map (115 objects, 0 points outside)
wrote crypt.tmj, crypt.tiles.png

Tiled gids: 1 wall, 2 floor, 3 door, 4 tree, 5 lift, 6 airlock, 0 empty. --tile sets the tile size (32 px), --encoding csv|base64 the layer data (base64 is zlib), --csv also writes each layer as Tiled's own CSV. The decks of a ship are tile layers of one map. The Tiled floor count (835) is lower than check's passable count (854) because doors are their own gid.

A deck plan gives one Universal VTT file per deck (--deck N for one), at 50 px per square or the recipe's if larger; space counts as wall, a lift as floor, and the airlock's outer door is a portal.

python scripts/mpw.py export ship.map --to uvtt -o ship.dd2vtt
PASS: deck 1 uvtt: loads, pixels_per_grid a whole number (ppg 50, 112 walls, 14 portals, 13 lights)
PASS: deck 1 uvtt: walls inside the image (112 walls, 0 points outside 40x21)
PASS: deck 1 uvtt: every door ends on a wall (0 door ends off a wall)
PASS: deck 1 uvtt: image matches the grid (2000x1050 px for 40x21 squares at 50)
PASS: deck 1 uvtt: colours alpha first, doors closed, no wall over a door (0 colours not ffRRGGBB, 0 portals not closed, 0 doors under a wall)
PASS: deck 1 uvtt: one portal per door (14 portals, 14 door squares)
PASS: deck 2 uvtt: loads, pixels_per_grid a whole number (ppg 50, 118 walls, 13 portals, 13 lights)
PASS: deck 2 uvtt: walls inside the image (118 walls, 0 points outside 40x21)
PASS: deck 2 uvtt: every door ends on a wall (0 door ends off a wall)
PASS: deck 2 uvtt: image matches the grid (2000x1050 px for 40x21 squares at 50)
PASS: deck 2 uvtt: colours alpha first, doors closed, no wall over a door (0 colours not ffRRGGBB, 0 portals not closed, 0 doors under a wall)
PASS: deck 2 uvtt: one portal per door (13 portals, 13 door squares)
wrote ship.deck1.dd2vtt, ship.deck2.dd2vtt

Hex battle maps

python scripts/mpw.py export hexes.map -o hexes.png
PASS: hex png: same size as the SVG (3050 x 1761 px, hex width 100 px)
PASS: hex png: every hex centre has its cell's colour (0 of 600 hexes differ)
wrote hexes.png

Engine heightmaps

The default size is the smallest the engine takes at or above the recipe's raster: 513 for Unity and 1009 for Unreal from a 512 px raster; --size changes it. Unity, Unreal and the mesh sample vertices from edge to edge; Godot and Roblox take pixel centres.

python scripts/mpw.py export isles.map --to unity -o isles.raw
PASS: unity heightmap: size the engine accepts (513 x 513, 16 bit, 526338 bytes)
PASS: unity heightmap: reads back within one step (worst 0.06469 m, step 0.12938 m, range -2400.0 to 6079.0 m)
wrote isles.raw, isles.import.json
python scripts/mpw.py export isles.map --to unreal -o isles-unreal.png
PASS: unreal heightmap: size the engine accepts (1009 x 1009, 16 bit)
PASS: unreal heightmap: reads back within one step (worst 0.06483 m, step 0.12967 m, range -2400.0 to 6097.9 m)
wrote isles-unreal.png, isles-unreal.import.json
python scripts/mpw.py export isles.map --to godot -o isles.r16
PASS: godot heightmap: size the engine accepts (512 x 512, 16 bit, 524288 bytes)
PASS: godot heightmap: reads back within one step (worst 0.06477 m, step 0.12978 m, range -2400.0 to 6105.0 m)
wrote isles.r16, isles.import.json
python scripts/mpw.py export isles.map --to roblox -o isles-roblox.png
PASS: roblox heightmap: size the engine accepts (512 x 512, 8 bit)
PASS: roblox heightmap: reads back within one step (worst 16.64706 m, step 33.35294 m, range -2400.0 to 6105.0 m)
PASS: roblox colormap: every colour is a material, same size (8 materials used, 512 x 512)
wrote isles-roblox.png, isles-roblox.colormap.png, isles-roblox.import.json

The top of the range differs by target (6079.0, 6097.9, 6105.0 m) because each samples the heights at different points. Notes:

  • Unity rows are written north first; --flip writes south first. Which one Unity expects is not verified.
  • Godot gets .r16 by preference because Terrain3D reads PNG as 8 bit.
  • Roblox is 8 bit (a 33 m step on this world) unless --bits 16. Sea and lake beds are Mud; add water with the Sea Level tool. The colour table comes from the reference and was not checked in Studio.
  • A region that is not square still gives a square Unity or Unreal heightmap, with different metres per pixel east and north; Roblox and Godot keep the shape.

Terrain mesh

OBJ with x east, y north, z up, in metres. --exaggeration, --base MM (close it under the lowest point), --flat-sea, and --print-mm N for a print tile N mm on its longer side with a 2 mm base. -o FOLDER writes polywright's asset layout.

python scripts/mpw.py export isles-west.map -o west.obj --print-mm 150
PASS: mesh: vertex and face counts match the grid (56196 vertices, 112388 faces for 257 x 215 samples with base)
PASS: mesh: every face index is valid (0 bad faces)
PASS: mesh: watertight (every edge shared by exactly two faces) (168582 edges, 0 open, 0 shared by more than two, 0 same-way, volume 59778.6 mm3)
wrote west.obj, west.manifest.json

Print

PDF and PNG at a paper size: --paper A0..A5|Letter|Legal|Tabloid|WxH (mm, default A4), --landscape, --dpi (300), --bleed MM with crop marks on the trim lines (--no-marks drops them), --margin (10 mm), --fit contain|cover, --style. A name with no extension writes both files. Needs Chrome or Edge.

python scripts/mpw.py export isles.map --to print -o isles-a4.pdf --bleed 3
PASS: print pdf: MediaBox is the paper plus bleed within 0.5 pt (612.284 x 858.898 pt, wanted 612.283 x 858.898, difference 0.0000 pt (browser page was 613.92 x 860.88))
PASS: print pdf: one page, TrimBox is the paper (1 page(s), trim difference 0.0000 pt)
wrote isles-a4.pdf, isles-a4.print.json

The browser prints a slightly larger page; mapwright rewrites the boxes to the exact size and checks them.

Planet texture

python scripts/mpw.py export blue.map --to sphere -o blue.png
PASS: planet: texture is 2:1 (512x256)
PASS: planet: no seam where the edges meet (mean |col 0 - col 511| 1.29 vs 90th percentile adjacent-column 1.94 (limit x2.5 + 0.5 grey level))
PASS: planet: no pinch at the poles (pole rows uniform) (std of top row 0.00, bottom row 0.00 vs whole texture 86.35 (limit x0.50))
wrote blue.png, blue.sphere.json

Sector to T5

python scripts/mpw.py export spin.map -o spin.tab
PASS: T5 tab: reads back by header (57 of 57 worlds)
wrote spin.tab

Navigation rectangles

export --nav (or --to nav, since 0.11.0) merges the walkable squares of a dungeon or square battle map into rectangles with a list of portals between them, as JSON for a game engine. It checks its own output before writing.

python scripts/mpw.py export crypt.map --nav -o crypt-nav.json
PASS: nav: rectangles cover every walkable square exactly once (45 rectangles over 854 squares, 0 covered 0 or 2+ times)
PASS: nav: no rectangle covers a wall (0 wall squares covered)
PASS: nav: portal graph has the same connected components as the square grid (1 square components, 1 rectangle components)
wrote crypt-nav.json

The file's keys, and the length of each list:

['entrance', 'format', 'format_version', 'generator', 'goal', 'h', 'kind', 'moves', 'origin', 'portals', 'rects', 'seed', 'units', 'w']
{'entrance': 2, 'goal': 2, 'portals': 46, 'rects': 45}

Agent size (since 0.19.0)

--agent N exports the navigation for a body N squares wide: a square stays walkable only when the N x N block with its top-left corner there is all floor or door, then the rectangles and portals are built as before and the bars run on that eroded grid. The JSON gains "agent": {"squares": N, "anchor": "top-left"}. --agent 1 (the default) gives the same file as no flag. From a real run on v0.19.0 (gen dungeon --seed 3 --w 40 --h 30):

--agent walkable squares rectangles components
1 508 23 1
2 369 8 6
3 261 7 7

The components grow because one-square doors are too narrow for a wider body: the export tells you so honestly rather than squeezing through. Widen doors in the map if a large creature must pass.

Not built: Tiled or Universal VTT for hex maps.

Clone this wiki locally