Skip to content
knownframe
Star

Tool reference

Generated from the battlemap-mcp server at a020c64. Your assistant gets these same names, descriptions and parameters from the server when it connects; the server is named battlemap, so a client may show a tool as battlemap:ping or similar.

Most tools need an open map. Coordinates are woxels: 256 woxels make one tile, the origin is the top left, and y grows downward. Rectangles are [x, y, w, h] and rotation is in degrees. See working with maps.

Connection and setup

  • ping Check the bridge is up, and whether it is the bridge in this package.
  • get_status Report the current map: whether one is open, its size and center in woxels,
  • inspect_dungeondraft_installation Report bridge-install health; by default, no token or live connection is used.
  • install_dungeondraft_bridge Install or update the bundled bridge mod in Dungeondraft's mods folder.
  • set_verbose Turn per-command log bracketing on or off inside Dungeondraft.
  • log_marker Write a line into Dungeondraft's log to separate phases of a test run.

Assets and packs

  • list_asset_categories List asset categories, with how many assets each actually holds.
  • list_asset_packs Which asset packs are installed, and which this map can actually use.
  • list_assets List asset paths in a category, optionally filtered by a case-insensitive substring.
  • search_pack_contents Search INSIDE every installed asset pack, including packs this map lacks.
  • preview_assets LOOK at candidate assets before committing to one. Read-only.
  • prepare_map_with_packs Copy the open map into one that INCLUDES asset packs, and open it.
  • list_prefabs List Dungeondraft's pre-composed prefabs — furnished groups, ready to place.

Walls, rooms and floors

  • build_room Build a room in one call: a looped wall AND a matching floor on the SAME path.
  • draw_wall Draw a wall through a list of [x, y] woxel points. Returns the new element id.
  • merge_walls Join two matching open walls sharing one endpoint, in ONE undo step.
  • add_portal Add a door/window portal at a woxel position. Returns the new element id.
  • add_roof Add a roof from its RIDGE LINE. Returns the new element id.
  • add_floor Draw a solid floor shape — the bordered room floors a built map is made of.
  • place_pattern Place a tiled floor/pattern shape (the Building Tool's "Floor" / Pattern Shape).
  • generate_dungeon Run Dungeondraft's own procedural generator: a whole layout in one call.
  • generator_options Read or set the Map Wizard's generator dials.

Objects, prefabs and text

  • place_object Place an object (prop) on the current map. Returns the new element id.
  • place_objects Place many objects at chosen positions in ONE call and ONE undo step.
  • scatter_objects Scatter objects randomly over a rectangular area, with jittered scale and rotation.
  • place_prefab Place one of Dungeondraft's pre-composed prefabs by name.
  • modify_object Modify an existing object's scale, rotation (degrees), color, shadow
  • duplicate_object Duplicate an object by id, offset by (dx, dy) woxels. Returns the new element id.
  • add_text Add a text label at a woxel position. Returns the new element id and size.

Terrain, paths, water and caves

  • set_terrain_slot Assign a Terrain asset to a terrain slot index so it can be filled/painted with that slot.
  • fill_terrain Flood-fill the whole current level with a terrain slot.
  • fill_region Fill only a region with a terrain slot (e.g. floor a single room), in woxel coords.
  • paint_terrain Paint a soft circular terrain brush of a slot at a woxel position.
  • paint_path Paint a continuous terrain stroke (a road/trail) along a polyline in one call.
  • paint_material Paint a MATERIAL patch along a brush stroke. Returns what it painted.
  • get_terrain Read the terrain back: sample the painted terrain on a grid.
  • set_terrain_blending Choose how terrain slots blend into one another on this level.
  • repair_terrain Rebuild a level's terrain splat when the engine dropped it. Destructive.
  • draw_path Draw a path/road/river through a list of [x, y] woxel points. Returns the new element id.
  • add_water Add a body of water — a pond, pool, river bend, moat, or flooded room.
  • set_water_style Style this level's water: what KIND of water it is. Returns the result.
  • dig_cave Carve a cave along a path with the Cave Brush (the dig/blast tool).
  • get_cave Read the selected level's cave floor/entrance cell counts and actual colours.
  • set_cave_entrance Open or restore a circular section of cave border, as one undoable edit.
  • clear_caves Wipe the entire cave layer back to solid rock.

Lighting and map style

  • add_light Add a light at a woxel position. Returns the new element id.
  • set_ambient_light Set the map's ambient light colour — the single biggest lever on mood.
  • get_map_style Read map-wide building wear and grid style from the world's actual textures.
  • set_map_style Set optional finishing effects across the map, as one undoable edit.
  • set_trace_image Put a reference image under the map to trace over. Returns what applied.

Inspect and edit elements

  • list_elements List elements currently on the map with their ids, positions, rotation, scale and asset.
  • get_element Get details (kind, position, rotation, scale, asset) for a single element by id.
  • get_composition_snapshot Describe the current map's spatial structure for generation or review.
  • move_element Move any element to a new woxel position by id.
  • move_elements Move many elements by the same offset, in one call and ONE undo step.
  • delete_element Delete any element from the map by id. Reversible with undo().
  • delete_elements Delete many elements in ONE call and ONE undo step. Reversible with undo().
  • select_elements Select the given element ids in Dungeondraft's UI (replaces the current selection).
  • clear_selection Clear the current selection in Dungeondraft.
  • get_recent_nodes List the ids Dungeondraft has assigned to nodes it created, newest last.

Validation

Maps, levels and files

  • open_map Open a .dungeondraft_map file, replacing whatever is currently open.
  • save_map Save the map. Use this often — it is how work survives a crash.
  • get_save_directory Where save_map writes, and whether that directory exists.
  • set_save_directory Set the directory save_map writes into. Pass "" to clear it.
  • set_map_size Resize the current map, in TILES (a tile is 256 woxels).
  • list_levels List the map's levels (floors) with their index, id and label, plus the current index.
  • 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).
  • delete_level Delete a level (floor) by its id (see list_levels). Not undoable.
  • get_snap_settings Report the grid the user snaps to. Read-only.
  • inspect_map_file Summarise a .dungeondraft_map file without opening it. Read-only.
  • export_dd2vtt Write the open map as a Universal VTT file (.dd2vtt) for Foundry, Roll20,
  • import_dd2vtt Rebuild a Universal VTT export (.dd2vtt) on the open map.

Camera, screenshots and exports

  • screenshot Capture the current Dungeondraft window (the on-screen view) and return it as an image.
  • fit_elements Frame the whole map, or a group of elements, then screenshot() to see it.
  • focus_element Center the camera on an element by id (works for any kind, including text).
  • get_camera Report the editor camera: world-center position [x,y], zoom, and viewport size.
  • set_camera Pan and/or zoom the editor camera. Returns the resulting camera state.
  • export_map Render the entire current map to a clean image (no UI) and return it.
  • get_export Wait for an export that export_map started, and return its image.
  • get_operation Status of an export: state is rendering, completed or failed.
  • clear_captures Remove every server-generated screenshot, export, and asset preview,

Undo and checkpoints

  • checkpoint Mark the start of a request, so all of it can be undone in one call.
  • rollback_checkpoint Undo every edit this session made since checkpoint(label), in one call.
  • list_checkpoints Open checkpoints: label, whose, steps since, and whether rollback still reaches them.
  • undo Reverse the LATEST undoable edit (create / delete / move / modify / terrain / cave).
  • redo Re-apply the last edit reversed by undo().

Dungeondraft tool controls

  • list_tool_controls List a Dungeondraft tool's UI controls — its real, operable surface.
  • tool_action Press a button control on a Dungeondraft tool.
  • set_tool_option Set a value on a Dungeondraft tool's control.
  • select_tool Select a tool in Dungeondraft's UI, as clicking its button would.
  • get_tool_layer Read which layer a tool draws on, and the range of layers that exist.
  • set_tool_layer Set which layer a tool draws on, for everything it places afterwards.