Map

Know where you are and where that road goes — and click a room across town to walk there, without keeping a wiki tab open beside the game.

What it’s for

GemStone is big, and the part of it you can see is one room of prose. Everything else lives in your head or in a browser tab: which way the bank is, whether this alley connects back to the square, how far you drifted while hunting.

The map draws the town around you from the map database — rooms as squares, exits as lines, your room ringed — and recenters as you walk. Go inside a building and it swaps to that building’s floor plan on its own. Click any room you can see and you walk there, using the client’s own pathing. No Lich required, which is why it works on the phone too.

Set it up

Common setups

A corner mini map you never think about again

Download the data, add the map window, and send it to a zone where it can stay — a corner of the Right Bar works. Leave zoom at its default. Then forget it: it follows you, swaps to a floor plan when you step inside a building, and swaps back when you leave.

You’ll see: a small live map that always shows the block you are standing on, with your room ringed and its exits ticked around the square.

Reading a whole town without leaving your chair

Right-click the map and choose Open Map Explorer. It opens as its own OS window, so you can park it on a second monitor. Turn Follow off, drag to pan and scroll to zoom, then click a room to select it and read its details in the collapsible Description, Environment, Forageables, Tags, and Exits sections. Walk here sends you to the selected room; double-clicking a room does the same in one gesture.

You’ll see: the full town laid out, with any room’s title, tags, and exits one click away — and a trip starting the moment you press Walk here.

Tips & gotchas

⚠️ The mini map does not pan or zoom by gesture. Dragging it moves the window, and the scroll wheel does nothing to it. Zoom is the Custom map zoom checkbox in its right-click menu. Drag-pan and scroll-zoom live in the Map Explorer, and pinch-zoom on the phone.

⚠️ The map is GUI and mobile only. The terminal prints a one-line hint instead of drawing. The travel commands behind it work identically in all three.

An empty map is telling you which thing is missing. Each message means something different: “Download map data in Settings > Map (or point at your Lich folder)” means no database; “Waiting for a mapped room…” means the database loaded but your room hasn’t matched yet; “Generating map…” means the layout is being computed and will appear shortly. Layouts are generated once per location and cached on disk, so only the first visit waits.

Nothing downloads on its own. Download map data and .mapdb download are explicit actions. .mapdb on its own reports the loaded database, its room count, and which release you have.

Downloaded releases carry GemStone data. DragonRealms sessions get their map from a Lich install instead — set Lich folder under Settings ▸ Map.

Unmapped shop interiors are normal, not broken. Map maintainers leave most shop interiors out on purpose, because they change constantly. Walk into one and the map holds the street outside: what is on screen stays mapped truth.

Cartography mode sketches those interiors instead. Turn on Cartography Mode in Settings ▸ Map and unmapped rooms draw as dashed, dimmed ghost rooms hanging off the room you entered from. Dashed means “what your client saw this session”; solid means “in the database”. Ghosts are never saved — they vanish when you close VellumFE, so they can never go stale. Ghost capture runs whether or not the mode is on; the setting controls only whether you see them.

Your map learns things it never writes down. Run forage sense or a ranger’s sense and the response is captured for the room you are in, showing up in the Map Explorer’s Environment and Forageables sections. Like Lich’s in-memory map edits, these are session-only — the map database on disk is never modified.

Player-shop warrens get their own map per town, listed in the location picker as, for example, Mist Harbor (Player Shops). Walking in switches the map over the same as entering any other location, which keeps the town map readable.

Explorer edits survive map updates. The Explorer’s Edit toggle lets you drag a group of rooms to tidy a layout (hold Alt for a single room). Edits save as per-room override diffs layered on top of any community-curated overrides shipped with the data. Reset overrides clears only your own layer.

If the map is stuck on the wrong room, run .room. It prints how your current room resolved, including its id, location, and edge count. On connections that never report a room id, the map falls back to matching title, description, and exits — and only trusts an unambiguous match, holding in place otherwise.

Curated maps, satellites, and .mappromote

Two kinds of map exist behind the picture described above, and knowing which one you are looking at explains why some places are laid out beautifully and others merely correctly.

Curated base maps are the hand-drawn spine of the world — the street grid of Wehnimer’s Landing, a major outdoor area. VellumFE ships a roster of which rooms belong to which base map, embedded in the build; no external install is needed to get them. What ships is membership only: the list of rooms that form “the town”. No coordinates are ever imported. The client’s own layout engine places every room from scratch, every time. That is why a curated map still reflows sensibly when the map database gains rooms, instead of drifting away from a frozen picture someone else drew.

Satellite maps are the automatic remainder. Anything mappable that no base map claims gets split into connected chunks of the room graph, and each chunk becomes its own map — a bank interior, a treehouse, an entire hunting ground nobody has curated yet. Nothing about a satellite is authored. When curation grows, the split recomputes and satellites shrink or disappear on their own. Components smaller than two rooms are not minted as maps at all; they annotate the room you enter them from instead.

What you see: a curated location and a satellite both draw as an ordinary map and both appear in the Map Explorer’s location picker. The practical difference is editorial quality — a base map was scoped by a person, a satellite is whatever the graph handed it — and the fact that satellite names are generated defaults rather than chosen ones.

.mappromote is a contributor tool

⚠️ Most players never run this. .mappromote exists to move map layout edits out of your personal file and into a staging export intended to be merged into the project and shipped to everyone. If you only want your own map to look right, the Explorer’s Edit toggle already does that permanently — stop there.

The pipeline it serves: you tidy a map in the Map Explorer, those drags save as personal override diffs, and .mappromote hands you a file you can contribute upstream.

Three forms:

With no map resolved yet and no argument, it declines rather than guessing: No current map; .mappromote <map-key> or .mappromote all. Anything that goes wrong past that point reports as mappromote: <reason> — a map key with no personal edits, for instance.

On success it prints the number of maps promoted, the file it wrote, and their keys, followed by Ship it: merge that file into defaults/map_overrides.json and commit.

Where the file lands: map_overrides_promoted.json, written beside your personal map_overrides.json in the VellumFE config directory (~/.vellum-fe/, or wherever VELLUM_FE_DIR points).

Promotion is not a one-way trip out of your client. The staging file loads back every session as a community layer stacked over the shipped curation, so a promoted map keeps looking the way you left it on this machine immediately and across restarts. Merging it into the project is only what shares it with everyone else. Your personal layer is emptied for the promoted maps, by design — the edits reach you through the community layer now, and leaving them in both places would apply group offsets twice.

⚠️ Running .mappromote twice is safe now, and used to not be. A second promotion merges into the existing staging entry rather than replacing it, so a small nudge made after your first promotion no longer discards everything else you had staged. If you are on a build older than this fix, promote once per map and check the staging file before promoting again.

See also

• Travel (.go2) — the commands behind every map click
• Compass — the current room’s exits, for the step you are about to take
• Room Window — the room’s own prose and exits as text
• Travel & Day Passes — how the pathing engine routes, and what it costs to cross paid edges

[[windows]]
name = "map"
widget_type = "map"
title = "Map"
row = 0
col = 0
rows = 12
cols = 30
show_border = true
zoom = 16

[map]
lich_dir = "C:/Lich5"
mapdb_repo = "Nisugi/mapdb"
mapping_mode = false