# text-maps DSL — Reference Information-oriented, exhaustive syntax reference for the text-maps DSL. It answers "what exists and what does it accept". For a learning-oriented, step-by-step walkthrough, see the tutorials instead. This follows the [Divio documentation system](https://docs.divio.com/documentation-system/)'s Tutorials/Reference split. The reference is split per map kind, like the tutorials: | Map kind | Reference | Tutorial | |---|---|---| | Dungeons and buildings (`map dungeon`, `map building`) | [Dungeon reference](dsl-reference-dungeon.md.txt) | [Dungeon tutorial](dsl-tutorial-dungeon.md.txt) | | Hex maps (`map hexcrawl`) | [Hex map reference](dsl-reference-hex.md.txt) | [Hex map tutorial](dsl-tutorial-hex.md.txt) | This page holds what both kinds share: how to render a map, the editor's tools and the syntax conventions. The reference is written to be equally useful to a human skimming for a property name and to an agent generating DSL text programmatically: every construct's exact grammar, every property's accepted values, and the defaults that apply when a property is omitted are stated explicitly — nothing here relies on inferring behavior from an example. ## How to render a map - **Browser app**: paste/type DSL into the textarea; the SVG renders live. Each parse error is marked in the text: a ❌ at the start of its line, the offending word underlined in red, and the message in a tooltip when the pointer is over that line (the first one is also shown under the textarea). - **Native CLI** (no browser/JVM needed): ```sh text-maps -i map.txt -o map.svg # or .png (needs rsvg-convert/Inkscape/a Chromium browser on PATH) cat map.txt | text-maps -o map.svg text-maps map.txt # positional form: reads a file, writes SVG to stdout text-maps --help # full flag reference ``` - Most code blocks in the references are short fragments illustrating one construct's syntax, not full documents — assume a fragment continues whatever `map ...` header its section already introduced. For complete, standalone documents see the tutorials and the `examples/` directory. ## The visual editor's tools The browser editor has a tool for most declarations below; this reference names a tool by its icon where it writes one. Tools that do the same thing look the same on both map kinds. The cursor over the map shows the active tool and what it will paint or place (the terrain's colour, the POI, item or door), and the panel at the bottom of the tool bar names it with a one-line how-to. On a portrait screen (a phone or tablet held upright, or a window taller than wide) the editor stacks the map, the tool bar as one scrollable row, then the text; each flyout opens under or over that row. The **Layout** button in the top bar switches between *Auto* (follows the screen and its rotations), *Vertical* and *Horizontal*, and the browser remembers the choice. In either layout, drag the handle between the text and the map (or focus it and use the arrow keys) to give one more room; double-click it to go back to the default split. | Icon | Tool | Map kind | What it does | |---|---|---|---| | ![File](tool-icons/file.svg) | File | both | load an example, share a link, save or copy the map | | ![Undo](tool-icons/undo.svg) | Undo | both | undo (Ctrl+Z) | | ![Redo](tool-icons/redo.svg) | Redo | both | redo (Ctrl+Y) | | ![Map settings](tool-icons/map-settings.svg) | Map settings | both | the header's `compass:`, `scale:`, `coords:` and (hex) `blur:`, `line-width:`, `text-size:` and `topology:` (with the Turn slider, `turn:`, for a sphere or torus) | | ![Pan](tool-icons/pan.svg) | Pan | both | drag the map (flick it to let it glide), scroll with two fingers on a trackpad or Ctrl+wheel to move it, wheel or pinch to zoom (dungeon: double-click an item to edit it). Escape returns to Pan from any tool (a first Escape drops a half-drawn path, zone corner, pick or selection) | | ![Zoom out](tool-icons/zoom-out.svg) | Zoom out | both | | | ![Fit](tool-icons/zoom-fit.svg) | Fit | both | fit the whole map to the view | | ![Zoom in](tool-icons/zoom-in.svg) | Zoom in | both | down to about three hexes or cells across, however large the map | | ![Select](tool-icons/select.svg) | Select | both | select, move and delete what is on the map: a room, door, corridor or item, with handles to resize (dungeon); a POI, road, river, path or country (hex). Delete removes the selection; a selected POI (an icon, a name or both, or a zone's label) is renamed with the selection bar's **Rename…** or Enter, its icon changed with **Icon…** or removed with **Remove icon**, a selected road's, river's or path's kind, `name:` and `color:` set with the bar's kind list, Name field and Color list, and the bar's **Line** and **Text** set a selected road's, POI's or country's own `line-width:`/`text-size:` (hex); R / Shift+R turns a dungeon item or room a quarter turn, and the cursor shows where a selection resizes or turns. On a dungeon map, Ctrl/Cmd+C copies the selected room, wall, stairs, door, drawn corridor or icon and Ctrl/Cmd+V pastes it (on the active layer, set a little aside; an icon into the selected room); the popups' **Duplicate** button writes a copy right beside it | | ![Area](tool-icons/area.svg) | Area | both | drag a rectangle to select everything in it (right-click cycles the shape: on a hex map `qr`, `qs`, `rs`, then freehand; on a dungeon map freehand); drag the selection to move it, Ctrl/Cmd+C (or Ctrl/Cmd+X to cut) then Ctrl/Cmd+V to paste a copy with its top-left corner under the pointer, Delete to clear it, Escape to drop it. On a hex map, R / Shift+R turns the selection 60° clockwise / counterclockwise and H / V mirrors it left to right / top to bottom, about its middle hex (also from the bar above the map: ![turn left](tool-icons/rotate-left.svg) ![turn right](tool-icons/rotate-right.svg) ![mirror](tool-icons/flip-horizontal.svg) ![mirror](tool-icons/flip-vertical.svg)). Moved or pasted elements stay on their layers; on a hex map, an area set in a uniform terrain is filled back with it when it is moved, cut or cleared. Hex: terrain, labels, icons and the stretches of road/river/path inside it; countries stay put unless one lies wholly inside (see the [hex reference](dsl-reference-hex.md.txt#moving-and-copying-an-area)). Dungeon: the rooms and free-form shapes lying entirely inside, with the rooms' items, connections and notes (see the [dungeon reference](dsl-reference-dungeon.md.txt#moving-and-copying-an-area)) | | ![Layers](tool-icons/layers.svg) | Layers | both | create/delete layers, show/hide them, set their opacity and the active one | | ![Place POI / Add item](tool-icons/place.svg) | Place POI / Add item | both | pick an icon (or stairs, a ladder, a window) in its flyout, then click a hex or a room; on a hex map, **Text only** places a name with no icon | | ![Erase](tool-icons/erase.svg) | Erase | dungeon | click a room, item, door or corridor to remove it (on hex maps, the POI and terrain pickers have an Eraser) | | ![Add room](tool-icons/add-room.svg) | Add room | dungeon | click a room to attach a new, connected room to it | | ![Snap to grid](tool-icons/snap.svg) | Snap to grid | dungeon | write a `pos:` for every room where it is drawn now | | ![Merge](tool-icons/merge.svg) | Merge | dungeon | click a room, then a room touching it: they become one free-form room (a hole they enclose a solid `wall:`); or click a drawn corridor or flight, then another whose end meets it: they become one route. Escape drops the first pick | | ![Connect](tool-icons/connect.svg) | Connect | dungeon | click a room, then another: a door if they touch, a corridor if not; click a drawn corridor (a `connect:` with a `route:`) to put a door in it | | ![Open / Closed / Locked / Secret](tool-icons/door-open.svg) | Open / Closed / Locked / Secret | dungeon | the door Connect puts on the new connection: ![Open](tool-icons/door-open.svg) ![Closed](tool-icons/door-closed.svg) ![Locked](tool-icons/door-locked.svg) ![Secret](tool-icons/door-secret.svg) | | ![Path](tool-icons/draw.svg) | Path | dungeon | click square after square (or drag a straight run) to draw a corridor or stairs (a `connect:` with a `route:`, joining the rooms its ends run into, with a door there) or a solid `wall:` along a path, or a room from one corner to the other (**Room**); pick the kind, the width (**1**/**2**/**3**) and, for stairs, up or down next to it; click the last square again or press Enter to finish; the arrow keys draw too | | Terrain swatches | Left / right terrain | hex | the two terrains every terrain tool paints, as Paint's two colours: the left button paints the front swatch's, the right button the back one's; click a swatch to pick its terrain (or the Eraser). Picking leaves the drawing tool alone (from Pan, Select and the like it picks Paint terrain) | | ![Swap](tool-icons/swap.svg) | Swap | hex | swap the two terrains (also X) | | ![Pick terrain](tool-icons/pick.svg) | Pick terrain | hex | click a hex to take its terrain as the left one (right-click: the right one), then go back to the drawing tool used before; Alt+click does the same with any terrain tool, without leaving it | | ![Paint terrain](tool-icons/terrain.svg) | Paint terrain | hex | click or drag over hexes | | ![Terrain zone](tool-icons/zone.svg) | Terrain zone | hex | click two corners (right-click cycles the axis, then cancels) to fill a `zone`; a zone started with a right-click takes the right terrain | | ![Fill](tool-icons/fill.svg) | Fill | hex | click a hex: its whole area of one terrain (up to other terrains and hexes with none) takes the terrain, written as `hex`/`zone ... axis: qr` declarations appended at the end (with the Eraser, the area loses its terrain); on a hex with no terrain, its empty area (a hole left by a cut, say), up to the terrain around it or the edge of the map; Shift+click: every hex of that terrain on the map; one undo step | | ![Line](tool-icons/line.svg) | Line | hex | drag a straight line of hexes | | ![Hexagon](tool-icons/hexagon.svg) | Hexagon | hex | drag from the centre outwards: a filled hexagon of hexes | | ![Spray](tool-icons/spray.svg) | Spray | hex | hold the button and move: hexes scattered at random around the pointer | | **1** / **2** / **3** | Brush size | hex | how many hexes across Paint terrain, Line and Spray paint: one hex, a hex and its 6 neighbours, or two rings around it | | ![Magic wand](tool-icons/wand.svg) | Magic wand | hex | click a hex to select its whole area of one terrain, Shift+click to add another area; the bar above the map **Grow**s the selection by every hex touching it (empty ones too) and **Paint**s it with the left or the right terrain; right-click deselects | | ![Country](tool-icons/country.svg) | Country | hex | paint it hex by hex (![hex by hex](tool-icons/terrain.svg)) or by zone (![by zone](tool-icons/zone.svg)); a new country asks its name on the first hex (the flyout's **+** starts another one, its field picks an existing one) | | ![Draw](tool-icons/draw.svg) | Draw | hex | click hexes for a road, river or path (![Road](tool-icons/road.svg) ![River](tool-icons/river.svg) ![Path](tool-icons/path.svg)); click the last one again to finish | | ![Move, +/− hex, +/− zone](tool-icons/move.svg) | Move, +/− hex, +/− zone | hex | with a country selected, the bar above the map moves it or adds/removes ![hexes](tool-icons/hex.svg) and ![zones](tool-icons/zone.svg) | | ![Delete](tool-icons/delete.svg) | Delete | hex | the selection bar's delete button (same as the Delete key) | | ![Delete waypoint](tool-icons/delete.svg) | Delete waypoint | hex | with a road, river or path waypoint selected, the bar's button next to Delete removes just that point (the route keeps at least 2) | ## Conventions shared by both map kinds - **Line-oriented, column-sensitive.** A top-level *declaration* (`room`, `connect`, `hex`, `zone`, `road:`, `country:`, ...) starts at column 0 (no leading whitespace). A *property* belongs to the declaration immediately above it and must be indented by at least one space or tab — the exact indentation width doesn't matter (2 spaces is the convention used throughout this document and the codebase), only that it's indented at all relative to its own declaration. - **Properties** are always `key: value` — a key, a colon, then the rest of the line as the value (leading/trailing whitespace trimmed; surrounding `"double quotes"` are stripped if present, so `label: Foo` and `label: "Foo"` are equivalent — quote only when the value itself needs to start/end with whitespace, which is otherwise trimmed away). - **Blank lines and `#` comments** are ignored anywhere (`#` must be the first non-whitespace character on the line). - An indented line that isn't a `key: value` property (no colon), one with no declaration above it, or a property key the declaration doesn't know (a typo like `lable:`) is a parse error on that line rather than being skipped. So is a value that doesn't parse, inside a `connect:` or `door:` block as much as on a room or a hex. - **`import as `** lines can appear anywhere in the document (before or after the `map` header) and declare an Iconify icon set under a short alias, used for room features / hex POIs (see below). The path's final `/`-segment becomes the set's actual Iconify prefix: ``` import icon-sets.iconify.design/game-icons as gi ``` An icon key (`.:`) whose alias no `import` declares is a parse error on its own line, not a silently dropped icon. Browse available icons/sets at [icon-sets.iconify.design](https://icon-sets.iconify.design). Icons are fetched from `api.iconify.design` at render time and cached (disk for the CLI, `localStorage` in the browser); an unreachable or misspelled icon renders as a small dashed placeholder box labeled with the icon name, instead of failing the whole render. - **Which grammar a document uses** is decided by its first non-blank, non-comment, non-`import` line: `map dungeon`, `map building`, or `map hexcrawl`.