Configuration - BlueMap-Minecraft/BlueMap GitHub Wiki
General
The configuration files of bluemap are 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 files, bluemap generates example configurations for you when it is starting. In those generated config files every field has a comment above it with what it does and it's default value (if it has one).
core.conf
The core configuration: This config file contains core-settings that are needed for the basic functionalities if BlueMap.
accept-download: false
renderThreadCount: -2
metrics: true
data: "bluemap"
- The
accept-download
field defaults tofalse
but you need to set this totrue
if you want to use bluemap! Before doing that, please read the following carefully:
By changing the setting
accept-download
totrue
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.)
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 andrenderThreadCount: -2
its8 + (-2) = 6
threads.- The
metrics
field defaults totrue
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) - With the
data
field you can change the folder where bluemap saves 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.)
render.conf
The render configuration: In the render configuration you define exactly what and how BlueMap should render.
webroot: "bluemap/web"
useCookies: true
maps: [
{
id: "world"
name: "World"
world: "world"
# Advanced map optional config fields:
startPos: [500, -820]
skyColor: "#7dabff"
ambientLight: 0
renderCaves: false
minX: -4000
maxX: 4000
minZ: -4000
maxZ: 4000
minY: 50
maxY: 126
renderEdges: true
useCompression: true
ignoreMissingLightData: false
},
{
# ... more maps
}
]
-
The
webroot
field in therender.conf
defines the folder where your rendered maps will be saved and the web-app files will be generated. -
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. -
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! Themaps
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
If you want, you can change your map's even further:
- With
startPos
you can control the xz-position on the map that the camera will be centered on when you open the map. - 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
isfalse
, 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
andmaxZ
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. Is that valuetrue
, blocks at the edge will be rendered, otherwise the edges will be see-through. useCompression
can be used to turn off the tile-compression. (Usually tiles are compressed using gZip). Compression reduces the file-size by >80% so it is really not recommended to turn this off.- Normally BlueMap detects if a chunk has not yet generated it's light-data and omits rendering those chunks.
If
ignoreMissingLightData
is set to true BlueMap will render Chunks even if there is no light-data! This can be usefull for example if some mod prevents light-data from being saved correctly. However, this also has a few drawbacks:- For those chunks, every block will always be fully lit
- Night-mode might not work correctly
- Caves will always be rendered (ignoring the 'renderCaves' setting)
- The
webserver.conf
Webserver configuration: 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
in this config on the defined ip
and port
.
enabled: true
webroot: "bluemap/web"
ip: "123.45.6.78"
port: 8100
maxConnectionCount: 100
- With the
enabled
field you can enable (true
) and disable (false
) the integrated web-server. - The
webroot
field in thewebserver.conf
defines the folder that the webserver will host to the web. This normally should be set to the same value as thewebroot
field in therender.conf
. - The field
ip
defines the IP-address the web-server will bind to. If you omit this field, bluemap binds to all network-interfaces (0.0.0.0
). If you only want to access your app on the machine that is hosting the map, uselocalhost
. - With
port
you can change the port that the web-server binds to. The default port is8100
. - The
maxConnectionCount
field limits the max number of active connections that the web-server accepts simultaneously.
plugin.conf
Plugin configuration: This section is about server-interaction. It currently mainly controls how player-markers are handled.
liveUpdates: true
skinDownload: true
hiddenGameModes: [
"spectator"
]
hideInvisible: true
hideSneaking: false
- If you don't want any live data being used, set
liveUpdates
tofalse
. This disables the full live-updates module. - If
skinDownload
is set to true, BlueMap will download and update the current skin of each player to make it available for the web-app. - With
hiddenGameModes
you can control what gamemodes are visible on the map. By default everyone is visible, except players in spectator-mode. - When
hideInvisible
istrue
, players that have the invisibility effect will not be displayed on the map. hideSneaking
controls if a player that is sneaking should be visible on the map.