Added lots more detail about config parameters.

2021-05-15 13:14:41 -04:00 · 2021-05-15 13:14:41 -04:00 · 8897211ad4
parent 71afbe5949
commit 8897211ad4
1 changed files with 221 additions and 38 deletions
--- a/Configuration.txt.md
+++ b/Configuration.txt.md
@ -169,94 +169,273 @@ This component controls the inactive timer of the internal webserver. If you are

 ***

+### display-whitelist 
+This defines whether to count hiddenplayers.txt as a whitelist or not. Hiddenplayers.txt allows you to hide certain usernames from showing up on the web sidebar, if display-whitelist is set to true, only players in hiddenplayers.txt will show on the web sidebar. 
+The default is: 
 ```
-# Treat hiddenplayers.txt as a whitelist for players to be shown on the map? (Default false)
 display-whitelist: false
+``` 

-# How often a tile gets rendered (in seconds).
+***
+
+### renderinterval 
+This defines how often dynmap attempts to render tiles. Each tile is an image of your map, the size can range from just a few blocks^2 to thousands^2 depending on quality profile and zoom level of the tile being rendered. The average map will have tens of thousands of tiles, this setting should not be set above 1. It is measured in tiles per second. 
+The default is: 
+```
 renderinterval: 1
+``` 

-# How many tiles on update queue before accelerate render interval
+***
+
+### renderacceleratethreshold 
+This defines a threshold for how many tiles can end up in the render queue before Dynmap attempts to accelerate rendering tiles. Setting this too low can cause performance issues. It is measured in tiles. 
+The default is: 
+```
 renderacceleratethreshold: 60
+``` 

-# How often to render tiles when backlog is above renderacceleratethreshold
+***
+
+### renderaccelerateinterval 
+This settings defines the speed Dynmap will attempt to render at once the renderacceleratethreshold has been reached. Settings this too low may cause performance issues. It is measured in tiles per second. 
+The default is: 
+```
 renderaccelerateinterval: 0.2
+``` 

-# How many update tiles to work on at once (if not defined, default is 1/2 the number of cores)
-tiles-rendered-at-once: 2
+***

-# If true, use normal priority threads for rendering (versus low priority) - this can keep rendering
-# from starving on busy Windows boxes (Linux JVMs pretty much ignore thread priority), but may result
-# in more competition for CPU resources with other processes
-usenormalthreadpriority: true
+### tiles-rendered-at-once
+This setting controls how many tiles Dynmap attempts to update at once. This works in combination with renderinterval to greatly change the amount of tiles rendered per second. It is not recokmmended setting this value higher than the amount of CPU cores your server has. The default value is unset and Dynmap uses half the number of CPU cores on the server. Changing this setting will greatly affect server performance during full-renders and radius-renders but only have a marginal impact during regular update-renders. It is measured in tiles. 
+The default is: 
+```
+#tiles-rendered-at-once: 2
+``` 

-# Save and restore pending tile renders - prevents their loss on server shutdown or /reload
-saverestorepending: true
+***

-# Save period for pending jobs (in seconds): periodic saving for crash recovery of jobs
+### usenormalthreadpriority
+This setting tells Windows Operating systems to run the Dynmap render process at a normal priority (versus low priority as is standard for background processes. This can help make update renders more consistent and prevent Windows from stopping long renders. Linux pretty much ignores this setting but can result in unexpected behavior. 
+The default is: 
+```
+usenormalthreadpriority: true 
+``` 
+
+***
+
+### saverestorepending 
+This setting allows Dynmap to store render queues to resume a render after a server restart. We don't recommend you change this setting unless you have issues with Dynmap at startup or you have a very low power server. 
+The default is: 
+```
+saverestorepending: true 
+``` 
+
+***
+
+### save-pending-period
+This setting controls how often Dynmap saves the render queue to disk for crash recovery of jobs. This is measured in seconds. 
+The default is: 
+```
 save-pending-period: 900
+``` 

-# Zoom-out tile update period - how often to scan for and process tile updates into zoom-out tiles (in seconds)
+***
+
+### zoomoutperiod 
+This setting controls how often Dynmap checks to update zoom-out tiles. These are the tiles with "z" in the name, as they cover very large portions of the map Dynmap does not update the zoomout tiles with the same frequency as standard tiles. Setting this too low will result in performance decreases, setting this too high will result in slower updating of the zoomout tiles and cause the zoomed out tiles to be outdated. This is measured in seconds. 
+The default is: 
+```
 zoomoutperiod: 30
+``` 

-# Control whether zoom out tiles are validated on startup (can be needed if zoomout processing is interrupted, but can be expensive on large maps)
+***
+
+### initial-zoomout-validate 
+This setting controls if Dynmap checks to see if the zoomout tiles are up-to-date on server startup. This can be an easy way to force-update the zoomout tiles if some are out of date however can cause large performance penalties on server startup due to the large amount of rendering Dynmap will be doing. 
+The default is: 
+```
 initial-zoomout-validate: true
+``` 

-# Default delay on processing of updated tiles, in seconds.  This can reduce potentially expensive re-rendering
-# of frequently updated tiles (such as due to machines, pistons, quarries or other automation).  Values can
-# also be set on individual worlds and individual maps.
+***
+
+### tileupdatedelay
+This setting controls how long to delay tile updates after Dynmap detects a change from render-triggers. This setting should not be set too low as it may cause Dynmap to re-render the same tiles repeatedly. This settings can also be overridden in worlds.txt on a per-world or per-map basis to allow fine tuned control of how quickly Dynmap updates maps after activity. This is measured in seconds. 
+The default is: 
+```
 tileupdatedelay: 30
+``` 

-# Tile hashing is used to minimize tile file updates when no changes have occurred - set to false to disable
+***
+
+### enabletilehash
+This setting controls whether or not Dynmap compares the hashes of the tiles when it triggers an update. If the tile after an update is the same exact image (no visible changes) it will skip updating that tile to save resources. We do not recommend disabling this setting.
+The default is: 
+```
 enabletilehash: true
+``` 

-# Optional - hide ores: render as normal stone (so that they aren't revealed by maps)
+***
+
+### hideores 
+This setting tells Dynmap to render ores as regular stone. This only works with the default texture pack and is just a simple texture swap. Enabling this after the map has been rendered will require a re-render. 
+The default is: 
+```
 #hideores: true
+``` 

-# Optional - enabled BetterGrass style rendering of grass and snow block sides
+***
+
+### better-grass 
+This setting tells Dynmap to render grass and snow blocks in the [BetterGrass (Optifine) style](https://boilercraft.com/images/dynmap/bettergrass.png). Changing this setting after the map has been rendered will require a re-render.
+The default is: 
+```
 #better-grass: true
+``` 

-# Optional - enable smooth lighting by default on all maps supporting it (can be set per map as lighting option)
+***
+
+### smooth-lighting
+This setting tells Dynmap to use smooth-lighting when rendering the map. For an example, adjust the smooth lighting option in your Minecraft client. This setting can be overridden in worlds.txt on a per-world or per-map basis. Adjusting this setting after the map has been rendered will require a re-render.  
+The default is: 
+```
 smooth-lighting: true
+``` 

-# Optional - use world provider lighting table (good for custom worlds with custom lighting curves, like nether)
-#   false=classic Dynmap lighting curve
+***
+
+### use-brightness-table
+This setting tells Dynmap to use the light level of the blocks in the world to determine brightness. If set to false Dynmap will use the legacy lighting curve to render the map. This setting can be overridden in worlds.txt on a per-world or per-map basis. Adjusting this setting after the map has been rendered will require a re-render. 
+The default is: 
+```
 use-brightness-table: true
+``` 

-# Optional - render specific block names using the textures and models of another block name: can be used to hide/disguise specific
-#  blocks (e.g. make ores look like stone, hide chests) or to provide simple support for rendering unsupported custom blocks
+***
+
+### block-alias 
+This setting allows specific blocks to be hidden or appear as other blocks on the map. It is most useful for hiding this like chests or mob spawners however it can also be used to define simple placeholders for custom blocks from other mods. This setting has very specific syntax and must be set as `"minecraft:block": "minecraft:replacement"` If you are not using the modded version of Dynmap you don't have to include `minecraft:`.
+The default is: 
+```
 block-alias:
 #    "minecraft:quartz_ore": "stone"
 #    "diamond_ore": "coal_ore"
-  
-# Default image format for HDMaps (png, jpg, jpg-q75, jpg-q80, jpg-q85, jpg-q90, jpg-q95, jpg-q100)
-# Has no effect on maps with explicit format settings
+``` 
+
+***
+
+### image-format 
+This setting controls what file type and compression Dynmap should use when saving the tiles. Dynmap supports PNG, JPG, and (WEBP)[] files as well as different quality levels of JPG files. The standard profiles are `png, jpg, jpg-q75, jpg-q80, jpg-q85, jpg-q90, jpg-q95, jpg-q100`. PNG files are uncompressed and allow for the highest quality image of the map however take up the most space. JPG allows you to compress the images and save on space as well as network bandwidth with significantly smaller files. This setting can be overridden in worlds.txt on a per-world or per-map basis. **NOTE:** To use WEBP you must use Dynmap build 426 or later and include the webp tools on their system. (For detailed instructions on WEBP see this Reddit post.)[https://www.reddit.com/r/Dynmap/comments/ji7h87/support_for_webp_map_image_format_in_31snapshot/] 
+The default is: 
+``` 
 image-format: jpg-q90
+``` 

-#  use-generated-textures: if true, use generated textures (same as client); false is static water/lava textures
-#  correct-water-lighting: if true, use corrected water lighting (same as client); false is legacy water (darker)
-#  transparent-leaves: if true, leaves are transparent (lighting-wise): false is needed for some Spout versions that break lighting on leaf blocks
+***
+
+### use-generated-textures 
+This setting controls how Dynmap renders water and lava textures. If set true, Dynmap renders fluids as they appear in game. If set false, Dynmap renders static textures. 
+The default is: 
+```
 use-generated-textures: true
+``` 
+
+***
+
+### correct-water-lighting 
+This setting controls how Dynmap renders light levels of water and blocks under water. If set true, Dynmap renders fluids and blocks as they appear in game. If set false, Dynmap uses the legacy (darker) lighting engine. 
+The default is: 
+```
 correct-water-lighting: true
+``` 
+
+***
+
+### transparent-leaves 
+This setting controls whether or not Dynmap renders leaves as transparent. This setting needs to be set false for some mods and modded server versions for compatibility. There is no performance difference on vanilla. 
+The default is: 
+```
 transparent-leaves: true
+``` 

-# ctm-support: if true, Connected Texture Mod (CTM) in texture packs is enabled (default)
+***
+
+### ctm-support 
+This setting controls whether or not Dynmap uses the Connected Texture Mod (CTM) to render connected or multiblock textures. This is usually required by most texture packs/mods and should not be normally changed.
+The default is: 
+``` 
 ctm-support: true
-# custom-colors-support: if true, Custom Colors in texture packs is enabled (default)
+``` 
+
+***
+
+### custom-colors-support 
+This setting controls if Dynmap uses Custom Colors in texture packs to render the map. This is most useful for custom grass/water/leaf colors in texture packs, it does not affect custom biome shading. This is usually required by most texture packs/mods and should not be normally changed. 
+The default is: 
+``` 
 custom-colors-support: true
+``` 

-# Control loading of player faces (if set to false, skins are never fetched)
+***
+
+### fetchskins 
+This setting controls if Dynmap should fetch custom player skins for player markers. By default it is enabled. If this is disabled Dynmap will show all players with the Steve skin. 
+The default is: 
+```
 #fetchskins: false
+``` 

-# Control updating of player faces, once loaded (if faces are being managed by other apps or manually)
+***
+
+### refreshskins 
+This setting controls if Dynmap should update player skins once it has saved them. By default it is enabled. If this is disabled player skins will not update automatically. 
+The default is: 
+```
 #refreshskins: false
+``` 

-# Customize URL used for fetching player skins (%player% is macro for name)
+***
+
+### skin-url
+This setting tells Dynmap where to get player skins from. This should not normally be changed unless you know what you are doing. `%player%` is a macro for the player name. 
+The default is: 
+```
 skin-url: "http://skins.minecraft.net/MinecraftSkins/%player%.png"
+``` 

-# Enable skins via SkinsRestorer plugin instead of internal legacy implementation (disabled by default)
+***
+
+### skinsrestorer-integration 
+This setting tells Dynmap to integrate with the SkinsRestorer plugin to fetch player skins. This is usually required for offline servers or server that don't authenticate against Mojang. This is disabled by default. 
+The default is: 
+```
 #skinsrestorer-integration: true
+``` 

+***
+
+### render-triggers
+These settings control when and how Dynmap updates the map. Adjusting these can affect server performance and can be helpful to speed up or slow down map updates. Disabling all of the render triggers will effectively stop Dynmap from automatically updating. If all triggers are disabled a radius-render or full-render will be the only way to update the map. As of Dynmap 3.1 there are 17 options:
+* `playermove` This is not recommended to be enabled. If enabled, Dynmap will trigger all tiles that contain blocks that a player moves to be updated. This can be a useful debugging tool but will crash servers with multiple people on. 
+* `playerjoin` This is not recommended to be enabled. If enabled, Dynmap will trigger all tiles in chunks around a player to be updated on player join. This can easily be exploited by players and cause severe performance issues and crashes. 
+* `blockplaced` This is enabled by default. If enabled, Dynmap will mark tiles that contain blocks that were recently placed **by a player** to be updated. 
+* `blockbreak` This is enabled by default. If enabled, Dynmap will mark tiles that contain blocks that were recently broken **by a player** to be updated. 
+* `leavesdecay` This is enabled by default. If enabled, Dynmap will mark tiles that contain leaves that have decayed to updated. Disabling this setting can cause floating leaves to be present on the map after a tree has been broken and is not usually recommended to be disabled. Large servers with auto-tree chopping plugins may consider disabling this. 
+* `blockburn` This is enabled by default. If enabled, Dynmap will mark tiles that contain blocks that have recently been burned to be updated. This is not usually recommended to be disabled as blocks that have been burned may remain on the map but not in-game. 
+* `chunkgenerated` This is enabled by default. If enabled, Dynmap will mark all tiles within chunks that have recently been generated to be updated (rendered for the first time). If you have pregenerated your world to the border this can be disabled but is not recommended as it will cause no performance penalty. For low power servers this can make the server extra laggy during world generation. 
+* `blockformed` This is enabled by default. I don't know what this trigger does. 
+* `blockfaded` This is enabled by default. I don't know what this trigger does. 
+* `blockspread` This is enabled by default. I don't know what this trigger does.
+* `pistonmoved` This is enabled by default. If enabled, Dynmap will update tiles that contain recently activated pistons. This setting can cause performance issues if large flying machines or massive piston farms are used. If tileupdatedelay is set properly, this setting has very little impact on server performance. 
+* `explosion` This is enabled by default. If enabled, Dynmap will update tiles that recently contained explosions. 
+* `blockfromto` This is disabled by default. I don't know what this trigger does. 
+* `blockphysics` This is disabled by default. I don't know what this trigger does. 
+* `structuregrow` This is enabled by default. I don't know what this trigger does. 
+* `blockgrow` This is enabled by default. If enabled, Dynmap will mark all tiles that have grow events (trees, crops, etc.) to be updated. 
+* `blockredstone` This is disabled by default. If enabled, Dynmap will mark all tiles that have redstone updates to be updated. This setting can cause severe performance penalties on servers with large redstone contraptions and can be abused by players. It is not normally recommended.
+
+The default config for triggers is: 
+```
 render-triggers:
  #- playermove
  #- playerjoin
@ -275,7 +454,11 @@ render-triggers:
  - structuregrow
  - blockgrow
  #- blockredstone
+``` 

+***
+
+```
 # Title for the web page - if not specified, defaults to the server's name (unless it is the default of 'Unknown Server')
 #webpage-title: "My Awesome Server Map"