New Contributor Guide Locations

Adding a new map locations

Map locations can be added to the game in JSON. The process is reasonably well documented in doc/MAPGEN.md and there are two mapgen tutorials that go into more details than this page: beginning and intermidiate. There's also an additional document for adding roofs.

A map location is defined across multiple files.

• The basic map, including monsters, NPCs, vehicles, traps, and items, is defined in a file in data/json/mapgen/. Fire station mapgen are at data/json/mapgen/fire_station.json, for instance, and it's a good reference because it's a moderately complicated, single tile design that only has two variants so you can look at the JSON and compare it to the game and make sense of it.
• Maps can have their palettes defined in the mapgen/ JSON file, or in a separate file that is customarily stored in data/json/mapgen_palettes/
• One or more maps can be collected into an overmap special, defined in data/json/overmap/overmap_special/. The JSON objects in this file control how a map spawns, where it is relation to a city, etc.
• data/json/overmap/overmap_connections.json and data/json/overmap/overmap_terrain/ also deal with mapgen, but they are poorly documented so you may have to figure this out on your own.

The main document for mapgen is doc/MAPGEN.md. It's a little confusing at places, but you between this guide and the beginner guide to mapgen you should be able to figure it out.

More on data/json/overmap/specials.json

• "sym" represents the symbol used. You can look at other mapgen entries to match up ‘correct’ symbols.
• "color" is the color.
• "see_cost" determines how far away you can spot the location. You have a maximum number of tile-equivalents you can see, and a tile with a higher "see_cost" counts as more tile-equivalents.
• "mon_density" affects the density of creatures you place in your mapgen entry.
• "flags" are special tags that have particular effects. For example, the flag "SIDEWALK" will attempt to attach your location to a sidewalk. So if you’re making a house or readily accessible building, you want that flag.
• Important Note! There is an "occurrences" field in each object in specials.json, which is a list of two numbers like this [ 0, 4 ]. The first number is the minimum number of times your special will appear on an overmap, and the correct value for that number is always 0. Not 1, not 2, not 4, it should be 0. Yes, your overmap special is extra special and you want to see it on every map, but nevertheless, the minimum number of occurrences is 0.
• The second number is the maximum number of occurrences, which can be any number greater than 0.

Computers have a special and complicated syntax.