Maps, levels and files tools

open_map

Open a .dungeondraft_map file, replacing whatever is currently open.

Any unsaved work in the current map is lost — call save_map first if it matters.

Loading is asynchronous AND it restarts the bridge: mods load after the map does, so the bridge briefly stops answering and can come back on another port. By default this waits until the map Dungeondraft reports open is the one you asked for, and returns its size and level.

opened: false means that had not happened in time. The load may still be running: read note and poll get_status rather than opening again.

wait=False returns as soon as the command is accepted.

path: absolute path to a .dungeondraft_map file.

save_map

Save the map. Use this often — it is how work survives a crash.

filename: a bare name (".dungeondraft_map" is added if missing), written into the configured save directory — see get_save_directory. Omit it to save over the map already open.

The map you have open can always be overwritten; that is the point, and it is how you check in progress as you go. A file that EXISTS and is not your open map is refused, so a plausible-sounding name cannot destroy someone else's map. Pass overwrite=True only when the user has actually asked to replace that file.

A map that has never been saved has no path, so saving it needs a filename: without one Dungeondraft opens a modal Save As dialog, and a modal freezes this bridge until a human closes it.

Writing is asynchronous, so by default this waits until Dungeondraft reports it finished writing THIS path and returns completed: true. While a save is in flight Dungeondraft DROPS edits from the file, so the bridge refuses to change the map until it lands.

completed: false means the save did not confirm in time. It is probably still running: read note, poll get_status, and do NOT call save_map again — a second write of the same file is the one thing that cannot help.

wait=False returns as soon as the save starts, for a caller that tracks saving.in_flight itself.

If Dungeondraft does not start a save at all, this raises instead of replying. Read the message, because the two causes need opposite action: busy (retry in a few seconds), or wedged after a save crashed inside Dungeondraft — then nothing can be written this session, a restart is the only way out and it loses unsaved work, so stop building and tell the user. Any edit made while a save is unfinished also carries a save_warning.

get_save_directory

Where save_map writes, and whether that directory exists.

configured is the user's setting (may be empty); effective is what will actually be used, and exists describes THAT one. With no setting, it is a battlemap-mcp folder inside Dungeondraft's own map directory — created on demand, so this works with no setup and keeps generated maps separate from hand-made ones.

configured_missing means the setting points at a directory that is gone. Saving falls back to the default rather than failing, and note says so; clear the setting with set_save_directory("") or point it somewhere real.

No parameters.

set_save_directory

Set the directory save_map writes into. Pass "" to clear it.

Persisted per install, so it survives restarts — a directory inside a temporary folder keeps being the answer long after the folder is gone. The directory must already exist; this will not create one. If it disappears later, saving falls back to Dungeondraft's own map directory and both get_save_directory and the save reply say so.

set_map_size

Resize the current map, in TILES (a tile is 256 woxels).

Uses Dungeondraft's own Change Map Size resize, so every level's terrain, cave and floor-tile rasters are resized and the saved map reopens. Each side must be 8 to 128 tiles, or 1 to 200 with the Unofficial Patch loaded (get_status.unofficial_patch). The top-left origin is kept: the map grows or shrinks on the right and bottom, nothing placed is moved, and shrinking does not delete what ends up outside. Set the size before laying out.

list_levels

List the map's levels (floors) with their index, id and label, plus the current index.

No parameters.

add_level

Add a new level (floor) to the map. Returns its id and label.

set_level

Switch the active level (floor) by its **id** (see list_levels).

Use the id field, not index: they are different numbers. Adding a level puts it at index 0 with a higher id, and deletions leave gaps in the ids.

delete_level

Delete a level (floor) by its id (see list_levels). Not undoable.

Refused when it would remove the map's only level.

get_snap_settings

Report the grid the user snaps to. Read-only.

Dungeondraft's snapping (and the Custom Snap Mod's square or hex grid) moves the MOUSE, so coordinates you pass are placed exactly as given. Placement tools take snap to match the user's grid instead:

'none' place exactly where asked. Pass it only when the user asks for exact coordinates; otherwise leave snap out, and the user's Placements choice in Dungeondraft's Battlemap MCP Bridge panel applies. 'auto' snap to the Custom Snap Mod's grid when the user has snapping on and the mod enabled - where their own cursor would land. Otherwise nothing moves, and the reply says why. 'grid' snap to the mod's grid if it is enabled, else to the grid Dungeondraft's own tool uses: the tile (256) for walls, rooms, lights, moves and prefabs, the half tile (128) for objects, doors and windows, paths and copies. Ignores the S toggle.

Returns vanilla_snapping, mod_loaded, mod_enabled, preset, placements (the panel's default for an omitted snap, with a note on using it) and grid (geometry square/hex_h/hex_v/isometric, interval, offset, radial mode). Isometric snaps as horizontal hex where the mod does (snaps_like), and is otherwise reported and never applied. On a hex map, build on that lattice and say so. Never change the user's snap settings; they are theirs.

No parameters.

inspect_map_file

Summarise a .dungeondraft_map file without opening it. Read-only.

Works with Dungeondraft closed, and on maps the user downloaded or was sent. Reports what a render cannot show:

• packs: each pack the map includes, whether it is installed and how many textures use it. packs_missing are not installed: those elements will be missing when the map opens. Check this before opening someone else's map.
• packs_used_but_not_included: elements Dungeondraft drops on load.
• per level: element counts, ambient light, terrain slot shares, materials by layer and coverage, paths by texture, width and layer, the most used objects with their scales, lights (range in the editor's units) and portals, with vtt_reversed: doors left open or windows closed, which swap roles in a VTT export.
• warnings: each of the above that will cause a visible problem, and why installed is null if the pack folder could not be read.

compare_to: a second map to compare with, e.g. a rebuild and its original. comparison lists count changes, objects and paths only in one map, scale and terrain share changes.

Lists stop at 25 entries per kind; counts are complete.

export_dd2vtt

Write the open map as a Universal VTT file (.dd2vtt) for Foundry, Roll20, Arkenforge and other VTTs. Read-only for the map.

Contains the map image (rendered like export_map), its walls as sight lines broken at each door and window, every portal (closed = an openable door, open = a window, which is all a VTT can tell), lights, the ambient light, and an outline for each object that blocks light.

path: absolute file to write. Omitted: beside the saved map, named after it. An existing file is refused unless overwrite=true.

ppi: pixels per grid square in the image (Foundry's default is 100).

grid: draw the grid into the image; VTTs usually draw their own.

Object outlines are the drawn area's bounding box, coarser than Dungeondraft's own export. Check vtt_reversed_portals from validate_floorplan first: a door left open arrives as a window.

import_dd2vtt

Rebuild a Universal VTT export (.dd2vtt) on the open map.

Without confirm it only reads the file and reports what it would do. Show the user, then call again with confirm=true. It recreates:

• walls from line_of_sight, rejoined through each doorway so doors mount;
• portals at their exported width: closed ones (a VTT's doors) as portal_asset, open ones (its windows) as window_asset. The export has no door/window field, so a map that had them reversed comes in reversed; compare with the trace;
• lights (colour, range, intensity, shadows) and the ambient light;
• the export's image as a trace under the map (trace=false to skip).

It never picks art: blockers lists each sight-blocking object outline (objects_line_of_sight) as center, rotation, length and width in woxels. Place a matching blocking object on each with place_objects.

The map must be the export's size (tiles); resize=true resizes it first. A region export is cropped to its region. Build on a new map: portals mount on the nearest wall, existing walls included.

One checkpoint, "import_dd2vtt", precedes the edits: rollback_checkpoint("import_dd2vtt") undoes them, except a resize, the ambient light and the trace. Hide the trace with set_trace_image(clear=true) before the final save_map.