Maps, levels and files

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.

save_map

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

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.