Repository navigation
Export
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.
python scripts/mpw.py export crypt.map -o crypt.dd2vttPASS: 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.tmjPASS: 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.dd2vttPASS: 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
python scripts/mpw.py export hexes.map -o hexes.pngPASS: 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
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.rawPASS: 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.pngPASS: 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.r16PASS: 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.pngPASS: 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;
--flipwrites south first. Which one Unity expects is not verified. - Godot gets
.r16by 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.
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 150PASS: 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
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 3PASS: 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.
python scripts/mpw.py export blue.map --to sphere -o blue.pngPASS: 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
python scripts/mpw.py export spin.map -o spin.tabPASS: T5 tab: reads back by header (57 of 57 worlds)
wrote spin.tab
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.jsonPASS: 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 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.
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.