Camera, screenshots and exports
Generated from battlemap-mcp v1.3.1. 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.
screenshot
Capture the current Dungeondraft window (the on-screen view) and return it as an image.
Fast; shows exactly what's visible including the current camera framing — so AIM FIRST, or you photograph whatever the last call left on screen: focus_element(id) for one thing, fit_elements() for the whole map. For a clean full-map render without UI, use export_map.
The result also names the saved file, at full resolution. The user does not see the image you receive, so when they ask to see the map, give them that path. Captures are kept until newer ones replace them (20 by default).
| Parameter | Type | Default | Description |
|---|---|---|---|
max_px | integer | null | null | shrink the image's long edge to this before returning it. Omit for the full capture. Worth setting when you are checking placement or coverage rather than judging materials and detail — a smaller image is a cheaper thing to look at, and every image stays in the conversation. |
fit_elements
Frame the whole map, or a group of elements, then screenshot() to see it.
Prefer this over set_camera: it computes the zoom for you, and set_camera's zoom is woxels-per-pixel, which runs backwards from the intuition that a bigger number means closer.
| Parameter | Type | Default | Description |
|---|---|---|---|
ids | integer[] | null | null | omit to frame the entire map — this is the normal way to look at your work. Pass ids to frame just those elements instead; ids without a position are skipped and listed in the 'missing' field. |
pad | number | 0.15 | extra margin as a fraction (0.15 = 15%). |
focus_element
Center the camera on an element by id (works for any kind, including text).
screenshot() to verify a specific element (e.g. a door cut into a wall).
| Parameter | Type | Default | Description |
|---|---|---|---|
id required | integer | ||
zoom | number | null | null | optional Camera2D factor to apply (LARGER = zoomed OUT). Follow with |
get_camera
Report the editor camera: world-center position [x,y], zoom, and viewport size.
zoom is a Camera2D factor where LARGER = zoomed OUT (zoom 0.5 magnifies 2x, zoom 2.0 shows twice as much). Use this to read the view before adjusting it.
No parameters.
set_camera
Pan and/or zoom the editor camera. Returns the resulting camera state.
x, y: world (woxel) center to move the view to (omit to keep current).
Follow with screenshot() to see the framed view.
| Parameter | Type | Default | Description |
|---|---|---|---|
x | number | null | null | |
y | number | null | null | |
zoom | number | null | null | Camera2D factor (LARGER = zoomed OUT; ~0.5 = a close look, ~2 = wide). |
export_map
Render the entire current map to a clean image (no UI) and return it.
ppi controls resolution (pixels per grid cell): higher = sharper but larger/slower. Dungeondraft abandons any export wider or taller than 16384 px without a word, so one that large is refused up front with the highest ppi this map allows.
The render is a tracked operation: this waits up to timeout seconds (max 600). If that runs out, the error names the operation; collect the image with get_export rather than exporting again. While an export renders, edits, camera moves and screenshots are refused — the exporter renders by moving the camera, and any of those would corrupt the image.
For a Universal VTT file (.dd2vtt) with walls, doors and lights, use export_dd2vtt.
| Parameter | Type | Default | Description |
|---|---|---|---|
ppi | integer | 40 | |
format | string | "png" | 'png' (default), 'jpg' or 'webp'. quality (1-100, default 90) applies to jpg and webp. |
timeout | number | 120 | |
max_px | integer | null | null | shrink the long edge of the image RETURNED to you. The file written to disk keeps the resolution ppi asked for, so this costs the delivery nothing — it only makes the copy you look at smaller. ppi is the knob that makes the render itself faster. |
quality | integer | 90 | |
grid | boolean | null | null | False for a gridless image, the usual deliverable for sharing and for VTTs that draw their own grid; True to force it on. Omitted, the export matches the editor. The editor's grid is put back afterwards. |
get_export
Wait for an export that export_map started, and return its image.
Use it when export_map ran out of time: the render carries on in Dungeondraft, and exporting again would only be refused until it finishes. Raises if the export failed, with the reason.
| Parameter | Type | Default | Description |
|---|---|---|---|
operation_id required | string | ||
timeout | number | 120 | |
max_px | integer | null | null | as in export_map — shrinks only the copy returned to you. |
get_operation
Status of an export: state is rendering, completed or failed.
Also reports chunks_rendered, elapsed_ms, the output path, the pixels it renders to and, on failure, error. Without an id, returns the current export (or null) and the recent settled ones. The bridge keeps the last 16 and forgets them when a map is opened or Dungeondraft restarts.
| Parameter | Type | Default | Description |
|---|---|---|---|
operation_id | string | "" |
clear_captures
Remove every server-generated screenshot, export, and asset preview, and every trace image it wrote but the newest.
This only deletes regular files directly in Dungeondraft's mcp_output directory whose names the server generates. It never recurses into the directory or removes other files a user has placed there. The newest trace is kept because the open map probably uses it; a map whose trace file is gone still opens, without its trace.
No parameters.