Connection and setup tools

ping

Check the bridge is up, and whether it is the bridge in this package.

bridge_current compares a hash of the source Dungeondraft is actually RUNNING with this package's mcp_bridge.gd. It is the only reliable answer to "is Dungeondraft on the latest bridge?", because Dungeondraft loads mods from a folder the user chooses and a file check can look in the wrong one.

False: Dungeondraft is running other code. Restart it to load a change, or reinstall into the folder it loads (inspect_dungeondraft_installation). None: the running bridge is too old to report its source. New bridges also report bridge_root (Dungeondraft's Global.Root for the executing mod) and process_id. These identify the running copy and process; they do not imply that files subsequently changed on disk are already loaded.

update_available appears when a newer release has been published. The companion cannot update itself: pass its message and url to the user.

No parameters.

get_status

Report the current map: whether one is open, its size and center in woxels, per-type element counts, and level info.

Call this first — map_center is the default placement point, and counts tell you what's already on the map.

map_file is the path the map was loaded from, "" if it has never been saved. open_map replaces what is loaded, so read this before opening another map if you mean to come back.

saving.in_flight is true while Dungeondraft is writing the file. Writes are refused during that window because edits made mid-save are dropped from it — wait and retry rather than treating the refusal as an error.

paused true means the user paused AI edits in Dungeondraft's Battlemap MCP Bridge panel: reads still work, edits are refused. Say so and wait for them. settings is what they chose there (update check, capture retention, default snap) and whether an environment variable overrides it.

unofficial_patch says whether Moulk's Unofficial Patch mod is loaded and its version. When it is, layer 1100 and maps up to 200 tiles are available. dialog_open true means a popup is holding Dungeondraft's input: if an edit seems ignored, ask the user to close it.

No parameters.

inspect_dungeondraft_installation

Report bridge-install health; by default, no token or live connection is used.

Check the folder recorded as [Mods] mods_directory in config.ini, or the platform default when none is set. Dungeondraft can also discover built-in mods, so other_copies must not be assumed inactive; one whose status is duplicate sits beside the bridge in the loaded folder. A bridge is found by its manifest under any folder name. Multiple discovery paths in a log are ambiguous; their order does not identify the loaded copy.

status: healthy | outdated (unmodified, but older than this package) | modified | unknown | missing.

This compares files on disk and reports historical evidence from the latest editor log. Log evidence is not proof of the current process. To learn which bridge Dungeondraft is actually RUNNING, call ping: its bridge_current hashes the live source. This check never launches Dungeondraft. With live=True, authenticate a read-only ping to report the executing mod's root, process ID and source identity separately from historical log evidence. Older bridges may not report their location.

install_dungeondraft_bridge

Install or update the bundled bridge mod in Dungeondraft's mods folder.

This is how a Claude Desktop extension or Claude Code plugin user gets the mod, and how they update it after updating the companion.

1. Call with no mods_dir: candidates lists the folders Dungeondraft loads, the one it is configured to use first. 2. Call with mods_dir to preview: show the user actions. requires_force true means a bridge is already there. 3. Once the user agrees, call again with confirm=true, and replace=true if a bridge is already there. The old one is moved to a backup outside the mods folder, never deleted.

It never starts Dungeondraft or changes a map. The user must then fully quit and reopen Dungeondraft and open a map; ping's bridge_current confirms the new bridge is the one running.

set_verbose

Turn per-command log bracketing on or off inside Dungeondraft.

When on, the mod writes >>> cmd {args} before each command and <<< cmd ok|ERR ... after. Godot writes engine errors to the same log with no indication of what provoked them, so this is what lets an error line be attributed to the command that caused it. Use it when auditing or debugging; leave it off otherwise.

log_marker

Write a line into Dungeondraft's log to separate phases of a test run.

Pairs with set_verbose: mark a phase, run some commands, then read the log between markers to see exactly what the engine reported for that phase.