Configuration

General

The main configuration file of bluemap (bluemap.conf) is formatted using HOCON. Please make sure you have a basic understanding of how to use HOCON and what "field", "key" and "value" mean in this context.

If you have no configuration file, bluemap generates an example config file for you. In this generated config every field has a comment above it with what it does and it's default value (if it has one).

Using the list maps you can define as many maps as you want. Each configured map will appear in a drop-down on the web-app where you can switch between them.
The generated config has 3 maps pre-configured as an example. Remember to remove the pre-generated maps if you don't use them!

The most basic config simply renders a world in the "world" folder in your current cwd and looks like this:

# set this to true, please read below what this means
accept-download: false

maps [
   {
      id: "my_world"
      name: "My World"
      world: "world"
   }
]

• The accept-download field defaults to false but you need to set this to true if you want to use bluemap! Before doing that, please read the following carefully:

By changing the setting accept-download to true you are indicating that you have accepted mojang's EULA,
you confirm that you own a license to Minecraft (Java Edition)
and you agree that BlueMap will download and use a minecraft-client-jar from mojang's servers (https://launcher.mojang.com/...)
The downloaded file contains resources that belong to mojang and you must not redistribute it or do anything else that is not compliant with mojang's EULA.
BlueMap uses resources in this file to generate the 3D-Models used for the map and texture them. (BlueMap will not work without those resources.)

• The maps field is a list ([]) of one or more objects ({}). Every object represents one map that bluemap will render. You can render multiple maps of multiple worlds, or even multiple maps of the same world if you want. Each map-object should have the following fields:
  • The id field to define the id of the map, this id can only contain normal letters (a-z) numbers and underscores and has to be unique. It is used for example as folder-name where the rendered map-models will be saved.
  • The name field to define the display-name of the map. This will be how the map is called in the web-app.
  • The world field to define the folder of the world you want to render

Other general configuration fields

• The metrics field defaults to true and controls if bluemap is sending some really small metrics reports. The report only contains the used implementation type (e.g. 'CLI' or 'Sponge') and the Version. This allows me to track the basic usage of BlueMap and helps me stay motivated to further develop this tool! Please leave it on :)
  (Since sponge has it's own metrics control, this setting will be ignored if you use bluemap as sponge-plugin)
• renderThreadCount defines how many render threads (processes) bluemap will create. Set this to 0 to maximize the utilization of your CPU (bluemap will create as many threads as available CPU-cores). If you set it to a negative value, bluemap will take the number of available cores and add the (negative) defined number to it. So with 8 cores and renderThreadCount: -2 its 8 + (-2) = 6 threads.
• With the data field you can change the folder where bluemap saves some files it needs during run-time or to save other data.
  (E.g. the downloaded minecraft-client file, other default resources and the state of your render-tasks if they got paused.)
• The webroot field defines the folder where the web-files will be generated to.
• The field webdata defines the folder where the generated maps are saved. This defaults to <webroot>/data. The web-app expects them to be in this folder, so don't change this if you don't have a real reason to do so.
• With useCookies you can disable the usage of cookies on the web-app. Cookies are only used to save users settings so they don't need to set them again each time they revisit the map.

Web-server

The integrated web-server is the easiest way to host your map to the web, so you can view it in your browser. If enabled, it will host (using http) all files in the folder defined by the field webroot on the defined ip and port.

To make the config more organized, all fields configuring the web-server have to be inside the webserver object:

webserver {
   enabled: true
}

• With the enabled field you can enable (true) and disable (false) the integrated web-server.
• The field ip defines the IP-address the web-server will bind to. If you omit this field, bluemap tries to find and use the default ip-address of your system. If you only want to access your app on the machine that is hosting the map, use localhost.
• With port you can change the port that the web-server binds to. The default port is 8100.
• The maxConnectionCount field limits the max number of active connections that the web-server accepts simultaneously.

Advanced

Bluemap also offers more advanced options for how to render your maps.
Here is an example of a map-configuration with all available fields used:

maps: [
   {
      id: "my_world"
      name: "My World"
      world: "world"

      skyColor: "#7dabff"
      ambientLight: 0

      renderCaves: false

      minX: -4000
      maxX: 4000
      minZ: -4000
      maxZ: 4000
      minY: 50
      maxY: 126
      renderEdges: true

      hires {
         tileSize: 32
         viewDistance: 4.5
      }
      lowres {
         pointsPerHiresTile: 4
         pointsPerLowresTile: 50
         viewDistance: 7
      }
   }
]

• The skyColor field controls the color of the sky using a css-style hex format. This is usefull for other dimensions like nether and end where the sky is darkred or purple.
• ambientLight defines the ambient light-strength that every block is recieving, regardless of the sunlight/blocklight. Useful if a world does not have any sunlight, like nether and end.
• If renderCaves is false, bluemap does not render any face that has a sun-light/sky-light value of 0. This removes unnecessary geometry and improves render-speed and most importantly the web-client performance by a lot! It might however sometimes remove faces you would see from above, e.g. the bottom of oceans or the wall below a big overhang. If you have a dimension that has no sunlight like the nether and the end you have to enable this setting.
• The fields minX, minY, minZ, maxX, maxY and maxZ define the "bounds" of the rendered world. So if you only want to render a specific area of your world you can do this here. With the y-fields you can also render only blocks in certain heights. You can use that to - for example - remove the ceiling of the nether to be able to see the lower areas in the render.
• If you limited the bounds of your map with the fields above, you can use the field renderEdges to define how those "edges" of your map will be rendered. This is best explained with an example:

If you want, you can even change the size of the rendered tiles and the resolution of the low-res models. This is not recommended though, wrong settings here can severely break bluemap or even crash the server or the web-app.
Here is the explanation for each of them:

• Fields in the hires object modify the high-resolution tiles. Those are the tiles you see if you zoom in on the map.
  • The tileSize field defines the amount of blocks each tile is wide. So with a value of 32, each map-tile consists of a 32 * 32 chunk of your world.
• Fields in the lowres object modify the low-resolution tiles. Those are the tiles you see if you zoom out on the map to get an overview.
  • This is a bit tricky now: The pointsPerHiresTile field defines the amount of low-res-points on a low-res-tile that each high-res-tile will occupy. So if the tileSize of the high-res tiles is 32 and the pointsPerHiresTile is 4, each low-res-point will contain a 32/4 = 8 -> 8 * 8 chunk of your world. This is why you have to always choose values that result in an integer if you use that calculation!
  • The pointsPerLowresTile field is the amount of how many low-res-points each low-res-tile is wide.

Important:
If you change tileSize, pointsPerHiresTile or pointsPerLowresTile you need to delete your previous renders! Delete the complete web/data folder! Otherwise you will get broken models.