Automation API

Protocol version 2

The Automation API is intended for external automation, not a modding or plugin platform yet. The surface may grow in future releases.

External scripts and tools can drive Daggermap over a local newline-delimited JSON (NDJSON) Automation API. Enable it in Settings → General → Automation.

Enable Automation API

Automation port

Allow remote connections

Automation status

Enable Automation API

Off by default. Turning this on makes the app listen on a local TCP port for incoming connections.

Automation port

TCP port for incoming NDJSON connections (default 8765).

Allow remote connections

When unchecked, the API listens on localhost only. Enable this only if you need to connect from another machine on your network and understand the exposure. There is no authentication — anyone who can reach the port can control the running app.

Automation status

Shows the bound address when the API is listening (for example 127.0.0.1:8765).

Protocol

Environment overrides (native app):

Semantics of success

A successful action or batch reply means the request was accepted for dispatch, not that the mutation has finished. On desktop, actions are queued and drained a few per frame. To confirm effects, follow up with a query (for example wait until golem.action_queue_count is 0) or wait a short moment.

A successful query or compute reply means the work finished on this line. Compute is never queued and never mutates the document.

Limits

Discover live limits, registered action ids, and compute ids via hello.

Coordinates, cells, and feet

The wire format for almost all geometry is world pixels. That is awkward if you think in battlemap squares or “5 ft,” but it is also stable: one number, independent of the current grid style. This subsection clarifies the conversion constants and how work in grid cells and labeled units.

Setting up your grid

Lock cell_size (and origin) before placing tokens or measuring. Every later conversion depends on those two numbers. If you skip this, you may be mixing the default 64px cell, a CV-detected size from the last background load, and whatever the user last dragged in the Grid tab.

Auto-detect (CV). On by default: Settings → General → Auto-detect grid (auto_size_grid_on_bg_load). After a load_background, Daggermap runs a computer-vision pass on the image (or video frame 1), then applies cell_size and origin to match the internal grid size to the printed grid if it detects one. A successful detect also sets (visible: false) so you do not double-draw a grid that is already in the art. It may apply an incorrect/non-matching grid on backgrounds with faint grids and or unusually patterned map designs. Scripts that must own the grid should turn it off:

{"intent":"action","action_id":"set_pref","args":{"auto_size_grid_on_bg_load": false}}

Manual / scripted grid. After the background is idle (session.net.bg_load_active is false at query depth ≥ 2, and session.grid.detect.done if you left auto-detect on):

{"intent":"action","action_id":"set_grid","args":{
  "cell_size": 64,
  "origin": [0, 0],
  "style": "square",
  "visible": true
}}

origin is percent of one cell, not world pixels. {0,0} puts the square grid at world (0,0).

Map size in world pixels. Query session.background: {loaded, tiled, width, height, asset_hash}. A non-tiled map occupies world coordinates [0, width] × [0, height]. Approximate cell counts: floor(width / cell_size) by floor(height / cell_size) when origin is {0,0}. Tiled maps are infinite; there is no finite pixel extent.

What to cache at setup

→ {"id":"g","intent":"query","path":"session.grid"}
→ {"id":"s","intent":"query","path":"session.scene"}

There is no API that accepts feet or cell indices as placement coordinates.

Three layers

World pixels     ←  what every x/y, p0/p1, and tokens_by_id.world_position uses
      ÷ cell_size (after subtracting the grid origin in world space)
Grid cells       ←  distance.cells; AoE fill internally
      × measure_units_per_cell
Labeled units    ←  distance.units + unit_label (“ft”); in-app measure ruler

World length in feet (Euclidean, ignoring the grid):

feet = world_pixels * (measure_units_per_cell / cell_size)

Grid-step distance is the distance compute, not that Euclidean formula.

Where the map origin is

For a square (or dots) grid, percent origin converts to world pixels as:

origin_world.x = (session.grid.origin.x / 100) * cell_size
origin_world.y = (session.grid.origin.y / 100) * cell_size

With the default origin {0,0}, the grid starts at world (0, 0). To work with cell indices, +X right, +Y down puts you in the battlemap quadrant. To script in terms of (col, row) 0-based, e.g., first column and seven rows down (0, 7), use:

cell_top_left.x = origin_world.x + col * cell_size
cell_top_left.y = origin_world.y + row * cell_size

A default-sized token (one cell) belongs at cell_top_left. Optional cell_center = cell_top_left + cell_size / 2 is only needed if you pass "center": true to add_token.

Hex grids (hex_a / hex_b) use the same origin percent field, but it is fractional axial (q%, r%), not Cartesian percent. Do not use the square formulas for hex; round through the grid (or stick to world points / distance / aoe).

add_token / add_tokens / move_token / document.tokens_by_id.<id>.world_position all use stored top-left. Optional "center": true on add treats x/y as the token center (no snap). Optional space":"screen" uses framebuffer pixels instead.

To drop a default-sized token onto square cell (col, row), pass top-left:

{"intent":"action","action_id":"add_token","args":{
  "path":"/tmp/goblin.png",
  "x": 0,
  "y": 0
}}

That is cell (0,0) when cell_size is 64 and origin is {0,0}. move_token to the same {x:0,y:0} leaves it in place.

Drawings, measure strokes, viewport origin, background size, and aoe geometry are all world pixels. Drawing thickness is world pixels (not feet).

Message envelope

Every request is a JSON object. Every response is a JSON object on its own line.

Request

Response

Success:

{"id":"1","ok":true,"result":{}}

Failure:

{"id":"1","ok":false,"error":"missing action_id"}

Errors are strings such as invalid JSON, unknown intent, path not found, action queue full, unknown compute_id, or action-specific validation messages (move_token requires id, no selection, …). The last failure is also mirrored under query path golem.last_error.

Quick start

1. Enable Settings → General → Automation.
2. Open a TCP connection to 127.0.0.1:8765.
3. Write one JSON object followed by \n; read one JSON line back.

Wire example (send the left side; receive the right):

→ {"id":"1","intent":"hello"}
← {"id":"1","ok":true,"result":{"protocol":2,"app":"daggermap",…}}

→ {"id":"2","intent":"action","action_id":"set_viewport","args":{"zoom":1}}
← {"id":"2","ok":true,"result":{}}

→ {"id":"3","intent":"query","path":"session.viewport"}
← {"id":"3","ok":true,"result":{"origin_x":0,"origin_y":0,"zoom":1}}

Any language that can open a TCP socket and encode/decode JSON works. Treat the stream as NDJSON — do not assume one recv equals one message.

Intents

hello

Capability advertisement. Optional, but recommended as the first call.

Request

{"id":"1","intent":"hello"}

Result fields

query

Read a filtered snapshot of app state. Queries run immediately (read lane).

Request

{"id":"q1","intent":"query","path":"session.viewport","depth":2}

Root keys (built only as needed for the requested path):

Unknown top-level paths return "path not found".

golem

session (depth ≥ 1)

projection_mode: 0 top-down, 1 isometric. draw_origin_snap: 0 free, 1 vertex, 2 cell.

At depth ≥ 2:

document

Document save payload (schema_version, scenes, assets, drawings, …). When depth is omitted/-1 or ≥ 2, includes:

"tokens_by_id": {
  "<uuid7>": {
    "id": "<uuid7>",
    "path": "…",
    "world_position": {"x": 0, "y": 0},
    "scale_x": 1,
    "scale_y": 1,
    "z_order": 0,
    "name": "",
    "fields": {}
  }
}

world_position is the token top-left in world pixels. Custom fields objects include key, label, current, note_text, max, show_on_canvas, label_size_dp, color.

Each scene in document.scenes[] includes id, sort_order, snap/measure fields, drawings[] (with p0/p1/points in world pixels and is_fog), tokens, grid, and background.

Prefer narrow paths (session.selection, document.tokens_by_id.<id>) over dumping the whole root when scripting.

action

Validate and enqueue (or, on web, immediately run) a single mutation.

Request

{"id":"a1","intent":"action","action_id":"add_token","args":{"path":"/path/to/token.png","x":0,"y":0}}

Success result: {}
Common errors: missing action_id, unknown action_id, action queue full, or a validator string.

compute

Synchronous read with arguments. Same line returns ok + result. Never queued; does not mutate the document.

Request

{"id":"c1","intent":"compute","compute_id":"distance","args":{"a":"<uuid>","b":"<uuid>"}}

aoe

Geometry matches draw_rectangle / draw_circle / draw_cone. Does not insert a drawing.

Result: { "token_ids": ["…"] } — tokens whose occupied AABB intersects the covered cells (or the geometric shape when fill_policy is shape).

distance

Use touch + cells for melee reach (adjacent footprints are 1; overlapping is 0). Use touch + world for Euclidean ranged gap (0 if the boxes overlap or share an edge). Points have no extent.

Result:

batch

Send up to 64 nested requests in one round-trip. Nested intents may be hello, query, action, compute, or nested batch.

Request

{
  "id": "b1",
  "intent": "batch",
  "requests": [
    {"id": "a1", "intent": "action", "action_id": "select_all_tokens"},
    {"id": "q1", "intent": "query", "path": "session.selection"}
  ]
}

Success result: { "responses": [ <envelope>, … ] }

The outer envelope is ok: true even when some sub-requests fail — inspect each entry in responses. Nested actions are still queued; nested query / compute still run immediately.

Actions

Two families share the same action intent:

1. Automation actions — purpose-built for scripting (tokens, viewport, draw, net, …).
2. UI actions — the same ids shown under Settings → Controls, so anything bindable in the app can be invoked over the API.

Call hello (or query session.actions at depth ≥ 2) for the live catalog.

Coordinates (summary)

Colors are strings resolved like the in-app pen (named colors or #RRGGBB / #RRGGBBAA where supported).

Document, scenes & viewport

set_grid fields (all optional, at least one required):

Keep toggle_snap_to_grid as a UI toggle if you want it; prefer set_grid snap_on_drop for scripts.

Settings

Writable keys include General (auto_size_grid_on_bg_load, golem_enabled, golem_port, golem_allow_remote, scales, language, …), Tokens (including token_use_full_resolution), Multiplayer (broker_url, net_display_name, …), and Themes (ui_theme plus style_* RRGGBBAA hex). Keybindings stay Clinamen action ids — not the opaque binding.json blob. Draw style prefs stay on set_draw_style; scene units stay on set_grid.

Tokens

add_tokens shapes:

{"dir": "/path/to/folder"}

{"path": "/tok.png", "positions": [[0, 0], [64, 0]]}

{"tokens": [{"path": "/a.png", "x": 0, "y": 0}, {"path": "/b.png", "x": 64, "y": 0}]}

Prefer add_tokens over many tiny add_token calls when dumping assets in. Positions in those examples are top-left on a default 64px square grid (cells (0,0) and (1,0) at origin {0,0}).

Name/field/move stay id-addressed; they do not require selection.

Draw & measure

World-space strokes. Point-pair shapes accept primary keys or a/b aliases.

snap: omit → follow scene AND-rule (draw_origin_snap and snap_on_drop); none/free/0 → no snap; vertex/cell override. Default scene draw_origin_snap is free, so omitted snap usually does not snap.

Multiplayer

UI actions (Controls)

Every id under Settings → Controls is registered as an action_id. Examples:

Args for selected UI actions

Selection-required actions fail validation with "no selection": move_token_*, remove_token, set_token_scale_up / _down, cut_tokens, copy_tokens. (remove_token also deletes the current drawing selection.)

Examples

Cache the grid, then place a token on cell (0, 7)

Assume a default square grid (cell_size 64, origin {0,0}). Top-left of column 0, row 7:

x = 0 + 0 * 64 = 0
y = 0 + 7 * 64 = 448

→ {"id":"1","intent":"query","path":"session.grid"}
← {"id":"1","ok":true,"result":{"cell_size":64,"origin":{"x":0,"y":0},"style":1,…}}

→ {"id":"2","intent":"action","action_id":"add_token","args":{"path":"/tmp/goblin.png","x":0,"y":448}}
← {"id":"2","ok":true,"result":{}}

Place a token and read it back

→ {"id":"1","intent":"action","action_id":"add_token","args":{"path":"/tmp/goblin.png","x":144,"y":72}}
← {"id":"1","ok":true,"result":{}}

→ {"id":"2","intent":"query","path":"session.selection"}
← {"id":"2","ok":true,"result":["018f…"]}

→ {"id":"3","intent":"action","action_id":"move_token","args":{"id":"018f…","x":216,"y":72}}
← {"id":"3","ok":true,"result":{}}

Grid-step distance in feet

→ {"id":"d","intent":"compute","compute_id":"distance","args":{"a":"018f…","b":"0190…"}}
← {"id":"d","ok":true,"result":{"cells":1,"world":64,"units":5,"unit_label":"ft"}}

Melee / edge-to-edge (occupied cells, AABB gap):

→ {"id":"t","intent":"compute","compute_id":"distance","args":{"a":"018f…","b":"0190…","mode":"touch"}}
← {"id":"t","ok":true,"result":{"cells":1,"world":0,"units":5,"unit_label":"ft"}}

AoE without drawing

→ {"id":"a","intent":"compute","compute_id":"aoe","args":{"kind":"rectangle","top_left":[0,0],"bottom_right":[64,64],"fill_policy":"touch"}}
← {"id":"a","ok":true,"result":{"token_ids":["018f…"]}}

Draw a measured line

→ {"id":"4","intent":"action","action_id":"draw_line","args":{"start":[0,0],"end":[144,0],"outline_color":"#c44","thickness":4}}
← {"id":"4","ok":true,"result":{}}

Validation failure

→ {"id":"5","intent":"action","action_id":"move_token","args":{"x":1}}
← {"id":"5","ok":false,"error":"move_token requires id"}

Wait for the write queue to drain

→ {"id":"6","intent":"query","path":"golem.action_queue_count"}
← {"id":"6","ok":true,"result":0}