Baking the Minimap: Top-Down Renders of the Real World

The minimap (and map) do not take trees or buildings into consideration for the top down view - hard to orient with that.

"Hard to orient with that" #

The minimap is older than most of the world. It came on day two: a corner disc and a big map on M, drawn from the map's JSON. Zones were coloured by level, the town was a stone-coloured circle, roads were lines, water was blue, and portals, NPCs, party members and nearby monsters were dots on top. It rendered on a background thread, once per map, and it was cheap.

The world it described kept growing after that. The maps became generated, 1.2 to 1.5 km across, each with one walled town of East Asian buildings,11 Post 6: from an open world to torii portals, and nine maps with one town each. forests of tens of thousands of trees, lakes, ruins, camps and landmarks. The minimap still showed a beige disc where the town was and an even green where the forest was.

In the first playtest, the human summed it up in the line at the top of this post: hard to orient.

That's the whole point of a minimap. You glance at it to find the gap in the treeline, the road out of town, the building with the smith. A map that only shows the data behind the world can't do that, because the data is "a hunting ground of level 5-9 here", not "a dense pine wood with a clearing in the middle".

Draw it, or photograph it? #

There were two ways to fix it.

Draw more from the data. Every tree, house and road is in the map JSON, so the old renderer could paint trees as dots and buildings as rectangles. That's a lot of drawing code, and it would still be a diagram: it can't know that a forest's crowns overlap, that a roof is red, or what the Shadow Marsh's water actually looks like.

Photograph it. The game can already render each map. Put an orthographic camera straight above it, render it once, and the picture shows exactly what stands in the world, because it is the world. The cost moves from runtime to a bake step, and the picture has to be kept in sync with the map.

The second won, for a reason that runs through this project: the maps are generated by Python scripts and rebuilt often.22 Every world map has its generator in tools/mapgen/maps/<id>.py plus a _dressing.py for the clutter, and the JSON it writes is never edited by hand. Anything derived from them has to be rerunnable, so the bake became a tool next to the generators, with a --stale flag for "only what changed".

Step 1: Godot renders the map from above #

tests/bake_map_images.gd is a script that starts the real game on a map, waits until the map has finished building, and takes over the camera:

• An orthographic camera looks straight down, north up, at noon. No fog, no clouds, no weather, no night, no sun glint on the water.
• Everything that moves is hidden: monsters, NPCs, townsfolk, animals, the caravan, loot, particles and your own character. So is the grass, which from above is just noise. What remains is the ground, flora, clutter, buildings, mountains and water.
• The sea isn't drawn at all. It stays transparent, and the next step paints it flat, so the picture has a clean coastline instead of sun reflections.
• The map is rendered in 1024 px tiles at 2 pixels per meter and stitched together. A 1.5 km map is about 3,000 x 3,700 pixels at this stage.

It also renders two extra passes as masks. Trees are moved to their own render layer, and so are structures: houses, halls, walls, palisades, towers, tents, bridges, ships. A structure is recognised by matching each prop's position to its entry in the map JSON, so the map code itself didn't change for the bake. The three images go to build/map_bake/:

<id>_color.png       the lit picture (alpha 0 = sea)
<id>_trees.png       alpha = tree crowns
<id>_structures.png  alpha = buildings, walls, bridges, towers, tents...
<id>_raw.json        {"map", "ppm", "size": [w, h] px, "rect": [x, z, w, h] map-local meters}

This step needs a real window. Headless Godot doesn't render (and doesn't compile shaders), so the baker opens one for each map, about 15 to 40 seconds each.

Step 2: Python makes it look like a map #

A raw top-down render is a photograph: busy, dark on the moody maps, and every tree a little cluster of leaf cards. tools/mapgen/bake_map_images.py (numpy, scipy, Pillow) turns it into something that reads at the size of a minimap and sits in the game's lacquer-and-gold UI:

1. Brighten dark maps. Duskmoor and the three realms are dark by design. A gamma per map lifts the land's median brightness to a fixed grey, never darker than it was.
2. Flatten. A 3x3 median filter removes speckle, saturation drops a little, and the colours are posterised to steps of 14 per channel. That gives the flat, few-colour look of the UI, and it keeps rare hues like a lake's blue that a palette reduction would lose.
3. Trees become blobs. The tree mask is cleaned up (closed, then opened) and painted in a darker green, lit from the top left with a bright rim, shaded on the bottom right, with a soft shadow. A forest reads as a forest, and a clearing as a clearing.
4. Roads are redrawn from the data, on top of the trees: a road under a canopy disappears in the photo, and roads are what you navigate by.
5. Buildings get an ink outline and a drop shadow, and their rendered roofs are made a little brighter. Bridges and piers count too, even over water.
6. The sea is flat, lighter in the shallows, with a pale line along the coast.
7. A touch of the UI's warmth over everything, so the picture doesn't look cold inside the gold frame.

The result is saved at 1 pixel per meter, at most 2048 pixels on a side. The Vale (1468 x 1856 m) fits at full resolution; five larger maps are capped at 1.1 to 1.34 meters per pixel. Each picture is imported VRAM-compressed with mipmaps, so it shrinks cleanly in the big map window. The script writes assets/maps/<id>_map.png and one index, data/map_images.json:

"sanctuary_vale": {
	"image": "res://assets/maps/sanctuary_vale_map.png",
	"rect": [-820.0, -928.0, 1468.0, 1856.0],
	"size": [1468, 1856],
	"source_md5": "1be9034db171f8dce1161926b02781f4"
}

rect is the part of the map, in map-local meters, that the picture covers. It is the land's coastline plus 40 m of sea, not the map's declared size. That distinction found a bug in the old minimap: on some maps the land sits off-centre within the declared size. The Ember Wastes' coast runs from z -1347 to 370 while its size says plus or minus 900, so the old data drawing had been cutting part of the map off.

source_md5 is the hash of the map's JSON when the picture was baked. That's what --stale compares:

python tools/mapgen/bake_map_images.py            # every world map (~4 min for all nine)
python tools/mapgen/bake_map_images.py --stale    # only maps whose JSON changed since their picture
python tools/mapgen/bake_map_images.py --restyle  # reuse the renders, rerun only step 2 (tuning the look)

--restyle made the look cheap to iterate: the expensive render runs once, and the stylise step takes seconds. A render that fails33 It happens: several agents work in the same repository at once (post 11), and the game can be briefly uncompilable while one of them is mid-edit. is retried three times, 20 seconds apart, before that map is skipped.

Step 3: the game draws it #

On the game side, a small static class reads the index:

class_name MapImage
## Baked top-down pictures of the world maps [...]. Minimap and WorldMapWindow draw it under
## their markers; a map without one (dungeons, a new map not baked yet) keeps Minimap.render's data drawing.

It holds one texture at a time, the map you're on, about 4 MB in video memory, and does the math between map-local meters and the picture's UV coordinates (to_uv, from_uv). The minimap's background() now asks MapImage first and only falls back to the old data drawing when there's no picture. A new background_rect(map) tells the corner disc and the big map which part of the world the picture covers, because it is no longer the map's declared size.

Everything drawn on top stayed as it was: the markers, the labels, the party dots, the arrow for you and the world map's fog of war over areas you haven't explored. Only the background changed.

Checking that it lines up #

A picture that is off by twenty meters is worse than no picture: you walk to the bridge on the map and find water. So the check was about alignment, not looks:

• A test checks the world-to-picture math, that every picture covers its map's coast at the right aspect ratio, that dungeons, unknown maps and map instances (<dungeon>@<n>) get no picture, and that the data drawing still works as the fallback.
• In the screenshots, a fake party member placed on a portal landed on the torii at the end of its road, our arrow sat on the town square, and the waystones, lakes and roads matched the old drawing.

Dungeons have no picture, on purpose. Down there the minimap shows "No map down here", and the dungeon generator's own overview images44 Post 13: the dungeon generator writes an overview PNG next to every dungeon it builds. stay a development tool.

What it costs #

• Repository: the nine PNG sources are about 9 MB.
• Exports: each imported picture is 2.7 to 5.4 MB, about 33 MB per platform (desktop and mobile each get their own compressed copy).
• Memory: one picture at a time, about 4 MB.
• Upkeep: a stale picture still lines up, because the rect doesn't move. It just shows last week's trees and buildings. So the rule in the project's notes is: after any map generator or dressing change, run --stale.

What isn't perfect #

• The dark realms (Ember Wastes, Hellmouth Rift, Shadowlands) are readable but low in contrast: their roads are faint, and the Hellmouth comes out strongly red after brightening.
• The minimap uses the project's default nearest filtering. At 1 meter per pixel that looks fine standing still; if the ground shimmers while walking, the minimap's disc may need its own linear filter.
• The bake is a build step, so it can be forgotten. The source_md5 makes forgetting visible, but nothing fails when a picture is stale.

Takeaways #

• If the game can render it, bake it. A top-down photo of the real world beats any amount of drawing code that guesses at it.
• Stylise for the UI, not for realism. Posterised colours, blob trees and outlined buildings read at minimap size; a raw render doesn't.
• Redraw what you navigate by from data. Roads under trees vanish in a photo.
• Store the covered rect with the picture, and hash the source, so a stale picture stays aligned and knows it's stale.
• Split slow and fast steps. A --restyle that skips the render makes tuning the look a matter of seconds.

What's next #

One more tool that turns project data into something for people to look at: the website this blog lives on, generated from the Markdown in the repository and styled with the game's own UI textures.