# text-maps — Agent guide How to draw a map with text-maps when you are an agent (an LLM with a shell), and how to hand the result to a human. Humans can follow it too: it is the shortest path from "I need a map" to "here is the link". The loop is: **write the DSL → render it to an image → look at the image → fix the DSL → repeat**, then **give the human an editor link** so they can review it and fine-tune it in the browser. --- ## 1. Get the command-line tool Prefer the native binary: it renders a map to SVG or PNG locally, with no browser, so you can look at your own output after every edit. | Platform | Download | |---|---| | Linux x64 | [`text-maps-linux-x64`](https://text-maps.tyrcho.com/downloads/text-maps-linux-x64) | | macOS (Apple silicon) | [`text-maps-macos-arm64`](https://text-maps.tyrcho.com/downloads/text-maps-macos-arm64) | | Windows x64 | [`text-maps-windows-x64.exe`](https://text-maps.tyrcho.com/downloads/text-maps-windows-x64.exe) | ```sh curl -fsSL -o text-maps https://text-maps.tyrcho.com/downloads/text-maps-linux-x64 chmod +x text-maps ./text-maps --help ``` From a checkout of the repository you can build it instead: `make native` (the binary lands in `native/target/scala-3.3.3/text-maps-native`). ## 2. Write the map A map is a plain text file. Its first line says which kind of map it is: - `map dungeon "Name"` (or `map building "Name"`): rooms, corridors, doors and features on a square grid. - `map hexcrawl "Name"`: terrain, regions, countries, roads, rivers and points of interest on a hex grid. Learn the syntax from the tutorials, step by step, one per map kind ([dungeon](dsl-tutorial-dungeon.md.txt), [hex map](dsl-tutorial-hex.md.txt)), and look things up in the reference ([dungeon](dsl-reference-dungeon.md.txt), [hex map](dsl-reference-hex.md.txt); every declaration, property and value). The fastest start is an existing example: every map in the [examples gallery](../examples/index.json) is a working DSL file you can download and edit, e.g. ```sh curl -fsSL -o map.txt https://text-maps.tyrcho.com/examples/dungeon/sunken_keep.dsl curl -fsSL -o map.txt https://text-maps.tyrcho.com/examples/hex/borderlands.dsl ``` `examples/index.json` lists them all (`id`, `title`, the paths of each one's `.dsl` source and rendered `.svg`, and absolute `dsl_url` and `editor_url` links), split into `dungeon` and `hex`: 10 of each, plus a few big maps marked `"large": true` that are slow to render and edit. ## 3. Render it and look at it ```sh ./text-maps -i map.txt -o map.png # an image you can look at ./text-maps -i map.txt -o map.svg # or SVG, which needs no extra tool ``` - **PNG** needs one of `rsvg-convert`, Inkscape, or a Chromium-family browser on `PATH`; use SVG when none is available. - **Look at the image** after every change — don't trust the DSL alone. Check that rooms don't overlap, doors sit on walls, labels are readable, and the map matches what was asked for. - A syntax error prints `Parse error at line N: …` and exits with a non-zero code: fix that line and render again. - Icons (`import … as gi`, then `gi.:`) are fetched from `api.iconify.design` and cached in `~/.cache/text-maps/icons`; an icon that can't be fetched renders as a dashed placeholder box with its name, so a missing icon is visible in the image. Keep iterating until the image is right. Small steps are cheaper than a big rewrite: change one thing, render, look. ## 4. Give the human a link to review When the map is ready, print its editor link and give it to the user: ```sh ./text-maps -i map.txt --url # https://text-maps.tyrcho.com/editor.html#map/the-sunken-keep/LYQwDgBA… ``` The link carries the whole map (compressed into the URL), so it needs no server or account: opening it shows the map in the editor, where the human can review it and fine-tune it with the visual tools, then share their own version back the same way (the editor's **Share** button copies such a link). `--url` still parses the map first, so a broken map fails instead of producing a broken link. Add `-o map.png` to write the image in the same run, and `--base-url ` to point the link at another deployment (a review environment, `http://localhost:8082/`, …). When you report back, include the link, the image you rendered (if you can attach files) and the DSL itself, so the user can read the map without opening anything. **Without the binary**: the link is `https://text-maps.tyrcho.com/editor.html#map/`, where `` is the DSL compressed with lz-string's `compressToEncodedURIComponent` (the same function the editor uses, e.g. the `lz-string` npm package). As a last resort, give the user the DSL and ask them to paste it into the [editor](https://text-maps.tyrcho.com/editor.html). ## 5. Skills for a whole map A skill packs a workflow for one kind of map: what to ask the user, the scripts to run, and what to check before handing over. For example, **text-maps-geographer** draws a hex map with plausible geography, in two passes (relief, rivers and climate first, then towns, farms, roads and borders). How to install one, and what each does: [agent skills](agent-skills.md.txt). --- ## Cheat sheet | I want to… | Do this | |---|---| | start a dungeon | `map dungeon "Name"`, then `room x` and `connect:` blocks — [tutorial](dsl-tutorial-dungeon.md.txt) | | start a hex map | `map hexcrawl "Name"`, then `hex ,` and `zone` blocks — [tutorial](dsl-tutorial-hex.md.txt) | | generate a dungeon | `generate dungeon rooms:12 seed:45` in place of rooms — [tutorial](dsl-tutorial-dungeon.md.txt#step-11-let-the-generator-draw-one-then-make-it-yours) | | copy an example | `curl https://text-maps.tyrcho.com/examples//.dsl` (see `examples/index.json`) | | see the map | `text-maps -i map.txt -o map.png` | | hand it over | `text-maps -i map.txt --url` | | look up a property | [dungeon reference](dsl-reference-dungeon.md.txt), [hex map reference](dsl-reference-hex.md.txt) |