--- name: text-maps-geographer description: Draw a geographically plausible fictional hex map with text-maps, in two validated passes - physical geography first (relief, coasts, climate, rivers), then human presence (farms, towns, roads, borders) where water and land favour it. --- # text-maps geographer You help a user get a hex map whose geography holds together: rivers run downhill from the ranges to the sea, the lee side of a range is drier, the cold is up high and towards the pole, and later the towns sit where people would actually settle. The map is a [text-maps](https://text-maps.tyrcho.com/) DSL file; that file is the only thing you keep and the user edits. Two passes, with the user's go-ahead in between: 1. **Physical geography**: shape, relief, climate, terrain, rivers, lakes. 2. **Human presence**, only once the user has validated pass 1: farmland, towns and cities, roads, countries and their borders. ## What you need - The `text-maps` command-line tool. Download it once (Linux x64 shown; macOS and Windows builds are listed in the agent guide): ```sh curl -fsSL -o text-maps https://text-maps.tyrcho.com/downloads/text-maps-linux-x64 chmod +x text-maps ``` - Python 3 (standard library only) for `scripts/worldgen.py`. - The hex DSL docs. They ship with this skill in `reference/` when it was installed from the zip, and are online as plain text: [agent guide](https://text-maps.tyrcho.com/doc/agent-guide.md.txt), [hex tutorial](https://text-maps.tyrcho.com/doc/dsl-tutorial-hex.md.txt), [hex reference](https://text-maps.tyrcho.com/doc/dsl-reference-hex.md.txt). Use only the declarations, properties and terrain names they list. If you need something they don't have, say so; don't invent syntax. ## 1. Ask what matters, once Ask in one short message, offering a default for each so the user can just say "go": - **Size and scale**: how many hexes across and down (default 64x40), and the distance per hex (default 25 km). A region, a continent, a world? - **Shape**: one continent, an archipelago, or a coast with the sea on the west. How much of the map is land? - **Latitude**: where the map sits between equator and pole (default 55 degrees at the top to 35 at the bottom, a temperate belt). This sets the cold and the heat. - **Prevailing wind** (default from the west) and **overall wetness** (dry, temperate, wet). The wind side of a range gets the rain. - **Relief**: a few great ranges, many small ones, or mostly flat. A free-text description is fine too ("something like western Europe", "a hot dry island chain"): turn it into these settings yourself and say which you picked. ## 2. Generate the physical map Map the answers to `scripts/worldgen.py` arguments and run it: ```sh python3 scripts/worldgen.py --name "The Westmarch" --width 64 --height 40 \ --shape continent --wind west --humidity 1.0 \ --lat-top 55 --lat-bottom 35 --mountains 1.0 --hex-km 25 --seed 7 > map.txt ./text-maps -i map.txt -o map.svg # or map.png if rsvg-convert/Chromium is installed ``` | Argument | Meaning | Default | |---|---|---| | `--width`, `--height` | hexes across, rows down | 64, 40 | | `--shape` | `continent`, `archipelago`, `coast` (sea on the west) | `continent` | | `--land` | share of land, 0-1 | 0.4 / 0.22 / 0.55 by shape | | `--mountains` | range strength, 0 (flat) to 2 | 1 | | `--wind` | where the wind comes from: `west`, `east`, `north`, `south` | `west` | | `--humidity` | 0.5 dry, 1 temperate, 1.5 wet | 1 | | `--lat-top`, `--lat-bottom` | latitude of the top and bottom rows | 55, 35 | | `--rivers` | river density, 0.5 fewer, 2 more | 1 | | `--hex-km` | scale bar distance per hex | 25 | | `--seed` | another seed gives another map from the same settings | 1 | The script computes heights, drainage, temperature and rain in memory and prints only DSL: one `zone` per run of the same terrain along a row, then the `river:` chains from source to mouth. Its first comment repeats the exact command, so the map can be generated again. Look at the image. If the overall shape is wrong, change the settings or the seed and run again; that's cheaper than editing hundreds of lines. Once the shape is right, fix details by editing the DSL: a later `hex` or `zone` at the same place paints over the earlier one, so add corrections at the end of the terrain section rather than rewriting rows. Render and look again after each change. Then give the user the image, the editor link and what you assumed: ```sh ./text-maps -i map.txt --url ``` The link opens the map in the browser editor, where they can repaint terrain and drag rivers themselves. Ask them to validate the physical map, or to send back their edited version (the editor's Share button gives a link; the DSL is in the editor's text pane). **Don't start pass 2 until they say the physical map is right.** ## 3. Add people, where they would live Work from the validated DSL, including the user's own edits. Put all of pass 2 in one block at the end of the file, so it shows as its own layer in the editor and can be hidden or dropped in one go: ```text layer "Settlement" hex 12,18 terrain: farmland ... ``` Where people settle, in order of preference: - **Fresh water first**: on a river, best where two rivers meet or where a river reaches the sea (a port), or on a lake shore. - **Coasts** with a sheltered bay; **plains, grassland, farmland** over hills; never on `mountains`, `glacier`, or in the middle of `desert`, `swamp` or `marsh` (an oasis or a causeway town is a deliberate exception, worth a label). - **Farmland** in a ring of 1-3 hexes around towns on good land (`plains`, `grassland`, cleared `forest`), along the rivers; herding in drier `plains` and `hills`. - **Roads** link towns along valleys and coasts, cross ranges at their lowest gaps, and follow rivers rather than climbing over hills. - **Borders** follow ranges and big rivers; each country has a core of good land around its capital. Label the larger places, keep small hamlets few, and keep labels from crowding the map. Render, look, fix, then give the image, the link and the DSL again. ## Review before you hand over - The DSL renders without a parse error, and you looked at the image. - Rivers run from high ground to the sea or a lake, and never stop mid-land. - Rain and terrain agree with the wind: wet and wooded on the wind side, drier behind the ranges. - Cold terrain (tundra, glacier) sits high up or towards the pole. - Towns sit on water, coasts or good land, linked by sensible roads. - You told the user what you assumed and what you changed by hand.