diff --git a/Configuration.md b/Configuration.md index 9f68704..1c6bbf7 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,24 +1,17 @@ ## General -The main configuration file of bluemap *(`bluemap.conf`)* is formatted using [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md). Please make sure you have a basic understanding of how to use HOCON and what "field", "key" and "value" mean in this context. +The configuration files of bluemap are formatted using [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md). 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 when it is starting. -In this generated config every field has a comment above it with what it does and it's default value *(if it has one)*. +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)*. -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 core configuration: `core.conf` +This config file contains core-settings that are needed for the basic functionalities if BlueMap. -The most basic config simply renders a world in the "world" folder in your current [cwd](https://en.wikipedia.org/wiki/Working_directory) and would look like this: -```yml -# set this to true, please read below what this means +```yaml accept-download: false - -maps [ - { - id: "my_world" - name: "My World" - world: "world" - } -] +renderThreadCount: -2 +metrics: true +data: "bluemap" ``` - 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: @@ -27,69 +20,80 @@ maps [ > 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: +- `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. +- 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)* +- 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.)* + +## The render configuration: `render.conf` +In the render configuration you define exactly what and how BlueMap should render. + +```yaml +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 the `render.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!** +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 `/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. + 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` 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. Is that value `true`, 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) -## 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`. +## Webserver configuration: `webserver.conf` +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`. -To make the config more organized, all fields configuring the web-server have to be inside the `webserver` object: -```yml -webserver { - enabled: true -} -``` - With the `enabled` field you can enable (`true`) and disable (`false`) the integrated web-server. +- The `webroot` field in the `webserver.conf` defines the folder that the webserver will host to the web. This normally should be set to the same value as the `webroot` field in the `render.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, 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: -```yml -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 - } -] -``` -- 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: - -![renderEdgesOnOff.jpg](https://bluecolored.de/paste/renderEdgesOnOff.jpg) - -## Live-Updates +## Plugin configuration: `plugin.conf` This section controls how player-markers are handled. ```yml liveUpdates {