Custom map styles

The basis

Terramap can display any web map in the Web-Mercator projection. Those maps are split into 256x256 pixels tiles and are accessed via a url, such as https://tile.openstreetmap.org/{z}/{x}/{y}.png (this is the main OpenStreetMap tile server). Those urls take 3 parameters, which are the tiles coordinates, replaced by {z}, {x} and {y} in the previous example. Z is the zoom level of the tile and X and Y are its coordinates.

For example, the URL https://tile.openstreetmap.org/0/0/0.png points the most zoomed out OpenStreetMap tile:

Terramap knows where to find those tile servers by looking up in a few places:

1. The mod file itself.
2. The main map file hosted at https://terramap.smyler.net/mapstyles.json , which it downloads when the game starts.
3. The Sledgehammer proxy's map file, which the BungeeCord proxy plugin sends on to Terramap clients when they join a Bungee network.
4. The server's map file, which the server side Forge mod sends to Terramap clients when they join a world.
5. The user's map file, which is loaded when the game starts or when the user reloads it.

Places last in that list have a higher priority, meaning that if they define a map that was already defined by a previous one, it will override it.

Depending on your setup, you want to use option 3, 4 or 5.

Legal disclaimer

While Terramap can technically work with any web service that follow the Web-Mercator standard, most of those services do not allow their use in projects like Terramap. YOU ARE SOLELY RESPONSIBLE FOR FOLLOWING THE TERMS OF SERVICES OF TILE SERVERS YOU CONFIGURE FOR TERRAMAP. This usually include, but isn't limited to displaying a copyright notice.

Map files

Regardless of the option you choose, the map file uses the same format, so this section is common to both server side and client side setup. The map file is in config/terramap_user_styles.json, which is in the following json format:

{
  "metadata": {
    "version": 13,
    "comment": "This file is a shortened version of the one at https://terramap.thesmyler.fr/mapstyles.json"
  },
  "maps": {
    "osm": {...},
    "osm_fr_hot": {...},
    "stamen_terrain": {...}
  }
}

As you can see, it is divided into two parts: some metadata and a list of map styles, identified by their ids (osm, osm_fr_hot and stamen_terrain in this case). The metadata part is purely optional and cosmetic and isn't actually displayed anywhere, although it is sent to clients for the server file.

Map style definition

Here is an example map style definition:

"osm": {
  "url": "https://tile.openstreetmap.org/{z}/{x}/{y}.png",
  "urls": [
    "https://a.tile.openstreetmap.org/{z}/{x}/{y}.png",
    "https://b.tile.openstreetmap.org/{z}/{x}/{y}.png",
    "https://c.tile.openstreetmap.org/{z}/{x}/{y}.png"
  ],
  "name": {
    "en_us": "OpenStreetMap",
    "fr_fr": "OpenStreetMap"
   },
  "copyright": {
    "en_us": "[\"\",{\"text\":\"© \",\"color\":\"white\"},{\"text\":\"OpenStreetMap\",\"underlined\":true,\"color\":\"aqua\",\"clickEvent\":{\"action\":\"open_url\",\"value\":\"https://www.openstreetmap.org\"}},{\"text\":\" contributors\",\"color\":\"white\"}]",
    "fr_fr": "[\"\",{\"text\":\"© Contributeurs de \",\"color\":\"white\"},{\"text\":\"OpenStreetMap\",\"underlined\":true,\"color\":\"aqua\",\"clickEvent\":{\"action\":\"open_url\",\"value\":\"https://www.openstreetmap.org\"}}]"
  },
  "min_zoom": 0,
  "max_zoom": 19,
  "display_priority": 1000,
  "allow_on_minimap": true,
  "max_concurrent_requests": 2,
  "debug": false
}

Let's go over each entry:

• urls is an array of urls pointing to tile servers that offer this map style. {z}, {x} and {y} are placeholders that are replaced with the right coordinates when needed. Terramap will cycle through those urls when making requests, to split the load on the different server, hopefully making things faster.
• url only exists for compatibility with Terramap version 1.0.0-beta5 clients, which should be going extinct by now, you can safely set this to any of the urls you have in urls.
• name is a list of names identified by their language key. This is used on the map style list. Terramap will use the name identified by the language key currently being used by Minecraft, or en_us (American English) if it isn't found. en_us should therefore always be present.
• copyright is a list of copyright notices identified by language keys in the same fashion as the names. These copyright are displayed on the lower right corner of the full-screen map. and must be in an escaped Minecraft json text component format, so hyperlinks are supported. To generate them easily, use https://minecraft.tools/en/json_text.php to get the json text and then https://www.jsonescaper.com/ to escape it.
• min_zoom is the minimum zoom level the map style supports. This is usually 0 (but not always).
• max_zoom is the maximum zoom level the map style supports. Check your tile server's documentation to get it.
• display_priority is the priority used to order the list of map styles. Higher means higher in the list.
• allow_on_minimap Set this to false to disable the use of the map style in the minimap (usually for copyright or api usage reasons)
• max_concurrent_requests is the maximum number of concurrent requests to the tile servers, per-hosts. Adjust this to fit your tile server's usage policy. For example, most OpenStreetMap tile servers asks users to go over two simultaneous requests per tile server.
• debug Set this to true so the map style is considered a "debug" one and is hidden to users that did not enable debug map styles in their client config. Similarly, if a server's config has debug map styles disabled, server debug map styles will be hidden to all players.

Client specifics

The map style config page

The map style config page can be accessed by opening the full screen map and clicking on the button, then going to page 2:

It gives you a summary of the currently loaded map styles, as well as the option to enable or disable debug map styles and reload the map styles loaded from your user config file. The "base" category corresponds to map styles loaded from the mod jar file and from terramap.thesmyler.fr, and the "Effective styles" category summarizes the loaded styles that will appear in the map style list.

The debug overlay

You can also use the debug overlay to get more information about the currently in-use map style. Press P to toggle the debug overlay:

There are useful information:

• The map id
• The map provider and its version, which indicates where the map style is configured:
  • BUILT_IN means it comes from the mod jar.
  • ONLINE means it comes from terramap.thesmyler.fr
  • PROXY means it comes from the Bungee cord proxy map file
  • SERVER means it comes from the server map file
  • USER means it comes from the user map file
  • INTERNAL means it has been generated by the code internally (so far, that's only the terrain debug map style)
• The map urls

Server specifics

On dedicated servers, the server map file can be reloaded with the /reloadmapstyles command. You need the terramap.commands.reloadmapstyles permission node for that (or be OP). Server custom map styles can be disabled by setting the sync_custom_maps config option to false.

Proxy specifics

Terramap proxy integration is done with Sledgehammer. Sledgehammer is not up to date yet and does not support the max_concurrent_requests, debug and urls field for map style definition, but apart from that, it is similar to the server setup. For more information: https://github.com/noahhusby/Sledgehammer/pull/11