Skip to content

Configuration

Jump to bottom Edit New page
Lukas Rieger edited this page Jan 10, 2020 · 20 revisions

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).
It also has 3 maps pre-configured as an example. Using the list maps you can define as many maps as you want. Each configured map will appear in a drop-down the web-app where you can switch between them. 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.

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 offers a lot more options to render your maps. Here is a more advanced example of a map-configuration with all available fields used:

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

      renderCaves: false
      ambientOcclusion: 0.25
      lighting: 0.8

      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
      }
   }
]
  • 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.
  • The ambientOcclusion field controls the amount of "shadow" you see in corners. This gives the geometry much more depth, but has a small impact on render-time.
  • lighting uses the light data from minecraft to make blocks with lower light-levels darker. Despite it's name, lighting defines the amount of "shadow" that is added, so a value of 0 makes every block fully lit.
  • 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:

renderEdgesOnOff.jpg

Add a custom footer

This wiki has moved!

It now lives here :)

Clone this wiki locally