Maps as Code

These last two weeks, I've been chugging away on one of my largest D&D software projects ever: turning my game's geography-based rules into code, and my mapmaking processes into custom software. The result is that maps become data, enabling all kinds of cool stuff as I integrate the maps with the rest of the application.

The pic above is a preview. This is, I hope, the first of several posts about the project. Let me talk you through it.

Maps and Apps

The best map I've done by hand is a partial map of the Canary Islands. I posted a version of this map on my birthday two years ago. Let me repost that image here:

Maxwell's hand-drawn, semi-historical rendition of the Canary Islands circa 1651, with territory broken down into 6.67-mile hexes, various settlements and localities, land routes, sea lanes, and a color and labeling scheme based on degree of civilization in each hex.

My game world's version of the Canaries in the year 1651 has served up over three real-time years of gameplay. The players can attempt to travel anywhere else on Earth at any time -- I don't restrict them -- and yet, two parties of players have found so much to do in the islands that they only occasionally talk about leaving for, say, nearby Morocco.

I've partially mapped Morocco. Here it is. Ugly, huh?

Researching Morocco has been a joy: I've learned loads about the civil war going on as the Saadi Sultanate implodes. But mapping Morocco has been such a huge effort that I'm still nowhere near finishing it after well over a year of halfhearted chipping away. Furthermore, when I'm done, all I will have is one more image. It won't be interactive. It won't be software...

...and it is my life quest to turn my D&D rules and world entirely into software that expands a DM's ability to design and run a massively deep and rich game world for his players.

Mapmaking feels like work. But developing the app for my game world1 is nothing but satisfying: I put in time and effort, and features come out. Battlemaps, character portraits that update live when items are equipped, and a 17th-century news gazette are just a few of the things I've shipped this year! Turning mapmaking into something I do within my own game world app will make it feel just as satisfying, and let me bring my coding skill to bear on the problem of map creation.

Structure and Scale

Turning maps into code and data is a lot of work. The rules involved are complex.

I map the Earth's surface in hexes 20 miles across. The Morocco map uses that scale. Each 20-mile hex has a value called infrastructure, derived from the placement and population of settlements: urban areas which my research shows were present in the year 1651. I'll skip the details of calculating and distributing infrastructure for this post.

20-mile hexes get broken down into hexes 6.67 miles wide, called "6-mile hexes" for brevity. The Canary Islands map uses the 6.67-mile scale. Seven 6-mile hexes fit fully inside one 20-mile hex.

Going back to the Canaries map, you'll see each 6-mile hex is labeled in the corner with a number from 1 to 8. This is the 6-mile hex's hex type, and hex type is based on how much infrastructure the parent 20-mile hex has. Two 20-mile hexes with the same infrastructure can break down into many different arrangements of 6-mile hexes. A type-1 hex bristles with urban development; a type-8 is lonely backcountry or wilderness without a single (human) soul in it.

The bread, hammer, and coin symbols are benefits, which measure how prosperous and advanced a 6-mile hex is. Benefits are calculated mainly from hex type (plus a few other factors, e.g. whether the hex borders the sea), and benefits in turn determine the presence of facilities: specific sites, institutions, and structures that concretely represent the degree of civilization in that hex. If you haven't had enough details crammed into your face already, feast on Alexis's wiki page on the hammer symbol to appreciate the depth of his game design.

I trust that I've given you a sufficient taste of the nuttiness of this whole thing. I'll stop here, even though I haven't gotten into road quality and placement; towns, villages, hamlets, and thorps; or how all of this connects to my game's tradegood pricing system.

All of the above detail has to be part of the new software. Until now, I've had to do all of that by hand: painstakingly calculating the spread of infrastructure across miles and miles of game terrain, rolling up 6-mile hexes, and then painting those in one at a time.

The Payoff

As I said, I've been chugging on this for two weeks. Checking my time tracker, I've spent 25-30 hours on this so far. And holy shit, would you look at how far I've gotten?!

The approach works. The system works. Starting with real-world elevation data from freely available sources like NaturalEarth, I can have a 20-mile map of any area on Earth in a few minutes. I can tweak the coastlines to better match the 17th century and twiddle elevations if the data has gaps. Settlements get plotted on the map automatically. I can draw the borders of realms, and within those, regions -- right on the map. Infrastructure automatically spreads out within regions. Pathfinding generates rough-draft, straight-line, hex-to-hex roads; several algorithms then intervene to make them more naturalistic.

It's even pretty, to my eye, and going to get prettier as I wrap up the fundamentals of the project and can turn my attention toward aesthetics.

So What's the Point?

This is why I rarely get anything out of someone else when they describe their setting—because they tell me, "This is how I do it." That's of no value to me. Tell me what doing it that way produces. Tell me at least why this is the way you've chosen.

Alexis Smolensk

To answer Alexis's call to action in that quote, here are some of the things I get out from maps becoming data.

Fast, detailed, re-generatable maps

Even the initial data download for a chunk of the Earth hundreds of miles across takes only a few minutes, and that's a one-time cost. Painting the map with realm and region borders is interactive and has intuitive Photoshop-like controls for fine-tuning edges. I can wait to break a hex down to the 6-mile scale only once the players are headed that way; the generator rolls the arrangement and I edit to taste (so long as I'm not breaking any of the generation rules!) I don't have to finish all of Morocco before the party sets foot in Asfi. And until players have visited somewhere -- at which point it is fixed in stone -- I can roll it again as many times as I like.

Increased precision of price system routing

The starting points for my tradegood pricing system are the answers to these questions: what settlements exist, what do they produce, and how far apart are they? All three are equally important. I recently posted about coding a better extraction pipeline for data to answer the first two questions. Now I have the equivalent for distances. Gone are the days of eyeballing distances on Google Earth to type into a Python file. In any region I've mapped, distances are now measured along the actual sea lanes and roads of varying quality.

Interactive, embedded information

Click a hex and you get its infrastructure, benefits, terrain, and everything else in it. Click a settlement or locality and you bounce straight to the wiki portion of my app.

I can calculate a route from the party's location to anywhere else on the map, and see how many hours that route would take them, along with what road segments, settlements, and localities they'd have to pass through.

For now, only I can see the map, but brother, you better believe I'm shipping this to players as soon as I can.

Rules I can change and rerun

On a handmade map, any rule change, miscalculation, or mistake meant tons of rework. Not any more.

In Conclusion

Nuff said. I'm going back to coding.

  1. For me, "world", "campaign", and "rules" are equivalent. World equals campaign because I run an open-world sandbox based on Earth in the mid-17th century; there is no preset "story". If one group of players stops playing, the next group commences play shortly afterward, as in-world time is reckoned, and does whatever they want. World equals rules because they feed back into each other. The presence or absence of game world elements is, from a certain perspective, a kind of rule about what currently exists in the game; in the opposite direction, rules define how the world evolves over time.↩