Base Plugin Settings

This page is out of date and is replaced by Configuration.txt and Installation

These settings are the top-level settings defined within the configuration.txt file. These settings, in general, cover the common behaviors of the plugin, independent of specific components, worlds, or maps. For component settings, see Component Configuration.

The core settings defined include the following:

• deftemplatesuffix : this optional setting, a string value, is used to modify the names of the templates associated with worlds. If undefined, normal worlds use the normal template, nether worlds use the nether template, and 'the end" worlds use the the_end template. When defined and non-blank, the name of the template used will be the default name, followed by and underscore, followed by the value of the deftemplatesuffix setting (e.g. if deftemplatesuffix is set to XXX, normal worlds will use the template normal_XXX instead of normal, nether worlds will use nether_XXX, ans 'the end' will use the_end_XXX). See HD Map Configuration for more details. Default template sets are included for vlowres, lowres, hires, and "" (blank).

• display-whitelist : if false (default), users are assumed to be visible until they've specifically been set to hidden using the /dynmap hide command. If true, users are assumed to be hidden until they've specifically been set to visible using the /dynmap show command.

• renderinterval : this setting, a floating point value in seconds, is used to control how often tiles needing to be updated (due to changes by players, for example) are processed. Setting this too low can cause extra load on the server, due to recalculation of repeatedly updated tiles. Default is 0.5 seconds. Most servers will perform without issue down to 0.2 seconds.

• renderacceleratethreshold : this setting, an integer, defines the size of the tile update queue allowed before the rate that tiles are processed shifts from the rate in renderinterval to the rate in renderaccelerateinterval. This is intended to prevent large tile backlogs from accumulating (which can happen when players are causing large amounts of new map territory to be generated) without requiring routine updates to be processed at a quick pace.

• renderaccelerateinterval : this setting, a floating point value in seconds, is used as the renderinterval value when the length of the tile update queue exceeds renderacceleratethreshold tiles in length.

• tiles-rendered-at-once : this setting controls the maximum number of update tiles that will be rendered concurrently. If not defined, the value defaults to 1/2 the number of processor cores. Settting this to lower values can reduce peek CPU use when large tile update load occur (from newly generated chunks, for example).

• usenormalthreadpriority : this setting, when set to true, causes the render threads to run with normal priority (versus minimum priority). This can help render performance on busy Windows boxes (preventing rendering from starving on busy boxes), but may result in competition for CPU with other processes. Most Linux JVMs ignore priority.

• zoomoutperiod : this setting, an integer value in seconds, specifies how often update processing of zoomed-out tiles is done. This done to prevent unneeded regeneration of the tiles due to repeated changes by players (such as when mining). Default value is 60 seconds.

• enabletilehash : this setting, a boolean, is used to enable the use of tile content hash codes, which are used to avoid re-encoding tiles that have not changed in value after re-rendering (such as due to changes in blocks that are not visible on the tile). This reduces processing load, zoom-out processing, and communications traffic with web clients.

• render-triggers : this setting, a list of strings, is used to enable various mechanisms for detecting the need to generate or update map tiles. The defined triggers are as follows:

  • chunkloaded : this trigger causes tiles to be updated based on the loading of map chunks. This trigger is no longer recommended - use chunkgenerated instead, as chunkloaded can cause significant and unnecessary tile recalculation. Retired in v0.31.

  • playermove : this trigger causes tiles to be updated based on the movement of players. This trigger is not recommended, as it will cause significant and unneeded tile recalculation.

  • playerjoin : this trigger causes tiles to be updated around the position where a player logs in.

  • blockplaced : this trigger causes tiles to be updated when a player places a block (recommended).

  • blockbreak : this trigger causes tiles to be updated when a player breaks a block (recommended).

  • leavesdecay : this trigger causes tiles to be updated when leaves decay due to the cutting of a tree (recommended)

  • blockburn : this trigger causes tiles to be updated when a block is destroyed by fire (recommended)

  • blockfaded : this trigger causes tiles to be updated when a block has faded (such as melted snow or ice) (recommended)

  • blockspread : this trigger causes tiles to be updated when a block has spread (lava or water) (recommended)

  • chunkgenerated : this trigger causes tiles to be updated when new map chunks are generated (recommended)

  • pistonmoved : this trigger causes tiles to be updated when pistons extend or retract (recommended)

  • explosion : this trigger causes tiles to be updated when blocks are destroyed by an explosion (recommended)

  • blockfromto : this trigger causes tiles to be updated when blocks are flowing into new blocks (lova, water) (recommended)

  • blockphysics : this trigger causes tiles to be updated when blocks move due to physics events (falling gravel, water, lava, sand) (recommended)

  • structuregrow : this trigger causes tiles to be updated when saplings grow into trees, or mushrooms grow into giant mushrooms.

  • blockgrow : this trigger causes tiles to be updated when blocks grow, such as crops and mushrooms

  • blockredstone : this trigger causes tiles to be updated when redstone currents change on a block (be very careful with this if you have redstone machines that run constantly)

• webpage-title : this setting, a string, is used to specify the title for the Dynmap maps web page. If not specified, it will attempt to use the 'server-name' property from server.properties. If that is undefined or set to 'Unknown Server', the title will default to 'Minecraft Dynamic Map'.

• tilespath : this setting, a string, specifies the path (either relative to the Dynmap plugin directory, or absolute) of where map tiles are to be generated (and where they are found by the internal web server).

• webpath : this setting, a string, specifies the root path for the internal web server. All files served by the internal web server (with the exception of the map tiles) are based on this path. The path can be relative to the Dynmap plugin directory, or absolute.

• webserver-bindaddress : this setting, an IP address, controls which network interfaces the internal web server will bind to. The default, 0.0.0.0, will cause the server to bind to ALL interfaces (which should be correct for most configurations). Setting to 127.0.0.1 will cause it to bind to only the localhost (which may be appropriate if an external web server located on the same box is being used). Other values need to match the address of the interface ON THE BOX (not public addresses outside a firewall or proxy).

• webserver-port : this setting, an integer, specifies which port the internal web server binds to. This defaults for 8123. Note: many operating systems require a process to run with root privileges in order to bind to a port below 1024.

• max-sessions : this setting, an integer, sets the limit on the number of concurrent sessions that the internal web server will allow to be active (limiting the resources used by the sessions and threads associated with those sessions). Default value is 30.

• http-response-headers : this setting, a set of attribute/value pairs, provides a way to have the internal web server include custom header values in all HTTP responses. The values under the attribute are formatted with the header field ID as the attribute ID, and the value of the header field as the string value of the attribute. For example:

    http-response-headers:
        Access-Control-Allow-Origin: "http://mydomain.com"
        X-Another-Header: "Another Header Value"
  

• disable-webserver : if set to true, the internal web server is disabled (this requires using an external web server, and the JSONFileClientUpdateComponent). Other configuration options require this setting to be false.

• allow-symlinks : if set to true, the directories under webpath or tilespath are allowed to contain symbolic links. If false, the internal web server will not follow symbolic links (this is a recommended practice that is followed by nearly all external web servers).

• timesliceinterval : this setting, a floating point in seconds, specifies a minimum time period between tile processing during /dynmap fullrender processing. Default value is 0.0 (no delay). Non-zero values can be used to reduce server load during full-renders, but will significantly lengthen processing time.

• maxchunkspertick : this setting, an integer, limits the number of map chunks loaded during a given server tick (50ms). As loading of map chunks is the main source of load on the Bukkit server's main thread, this can be used to limit any lag that may be resulting from map processing.

• progressloginterval : this setting, an integer, is the interval used for reporting progress on fullrender requests. The default (and minimum) value is 100.

• parallelrendercnt : this setting, an integer, is optional, and can be used to allow full-render processing to be done by more than one thread. The setting indicates the number of concurrent threads that will be used, and should be limited to the number of physical cores on the server (or less). Note: setting this will result in much more intensive CPU use, some additional memory use. Caution should be used when setting this to equal or exceed the number of physical cores on the system.

• updaterate : this setting, an integer in milliseconds, specifies how often the web clients should poll the server for updates (whether it be tile updates, chat messages, or player position updates). Setting this to a higher value can reduce web server traffic.

• fullrenderplayerlimit : this optional setting defines an option for suspending fullrender/radiusrender processing when the number of active player logins reach or exceed a given limit. Default is 0 (disabled), while a setting of 1 will result in fullrender/radiusrender processing being suspended while any players are logged in.

• showplayerfacesinmenu : this setting, a boolean, is used to control whether to show online players in the tray meny on the web clients. Default is to show the players (true).

• sidebaropened : this setting, a string, is used to optionally pin the sidebar menu permanently open ('true'), pinned by default ('pinned') or closed by default ('false'). Default is false.

• joinmessage : this setting, a string, is used to control the message reported in web chat when a player logs in to the server. The substitution macro, %playername%, is used to provide the player's name.

• quitmessage : this setting, a string, is used to control the message reported in web chat when a player logs off ofthe server. The substitution macro, %playername%, is used to provide the player's name.

• spammessage : this setting, a string, is used to control the message reported to web chat users that attempt to send messages too often.

• webprefix : this setting, a string, is used to provide a prefix for chat messages received from web clients. The escape sequence '&color;' can be used in place of the Bukkit color escape sequence.

• websuffix : this setting, a string, is used to provide a suffix for chat messages received from web clients. The escape sequence '&color;' can be used in place of the Bukkit color escape sequence.

• showlayercontrol : this setting, a boolean, is used to control whether the layer control is shown (setting this to false will cause it to not be shown, even if marker layers are defined). Default is true.

• check-banned-ips : this setting, a boolean, is used to control whether the internal web server checks the banned-ips.txt file to block access to the web client by banned IP addresses.

• persist-ids-by-ip : if true, player IP addresses and the associated player IDs are persistent, and will be saved on server shutdown and reloaded on server startup (allowing known IP address to player ID associations to accumulate). Default is true (0.29 or later).

• defaultzoom : this setting, an integer, specifies the default zoom level for the web client when it is first loaded by a user.

• defaultworld : this setting, a string, specifies the name of the default world for the web client when it is first loaded by a user.

• defaultmap : this setting, a string, specifies the name of the default map for the web client when it is first loaded by a user.

• followzoom : this optional setting, an integer, specifies the default zoom level for the web client when a player is selected to be followed.

• followmap : this ootional setting, a stirng, specifies the name of the default map for the web client to switch to, if needed, when a player is selected to be followed

• verbose : this setting, a boolean, controls how verbose the messages are for the Dynmap plugin during startup. Setting to false will significantly reduce reported messages and details.

• hideores : this setting, a boolean, controls the option to hide any ore blocks, making them appear the same as solid stone (preventing maps from being used to find exposed ores). Default is false.

• better-grass : this setting, a boolean, controls the option to render the sides of grass and snow blocks as they are done with the BetterGrass client mod (if set to true). Default is false.

• smooth-lighting : this setting, a boolean, provides the default setting for the smooth lighting option on all maps supporting the feature. Setting it to 'true' is a convenient way to enable smooth lighting on all maps that can use it. The setting is also defined on a per-shader basis, which can be used to control the feature on an individual map level. Enabling this feature will add approximately 10% to rendering processing cost.

• use-generated-textures: this setting, if defined and set to 'true', will cause texturepack based HD map renders to use generated textures for water, lava, and fire equivalent to those used by the Minecraft client. If false, the legacy textures in the texture.png and misc/water.png are used (pre-0.29 behavior). Setting this will require a full map render to see the proper results.

• correct-water-lighting: this setting, if defined and set to 'true', will cause texturepack based HD map renders to process lighting of water equivalently to the Minecraft client. If false, the legacy behavior - which results in darker water - is used (pre-0.29 behavior). Setting this will require a full map render to see the proper results.

• fetchskins : this setting, a boolean, controls whether the server will attempt to fetch skins for players during login. If set to false, no skins are fetched, and the default skin is assumed for all players. Default is true.

• refreshskins : this setting, a boolean, controls whether faces and other images derived from a player's skin are refreshed each login. If set to false, existing files are never refreshed (which can be useful if faces are locally managed or updated by the server administrator or another plugin). Default is true.

User Login Security Settings for Web Interface

The support for login-based security on the web interface can be controlled through the following settings:

• login-enabled : this setting, a boolean, enables login security support (if the setting is defined and set to 'true').

• login-required : this setting, a boolean, forces all web users to log in, in order to access the web interface (if the setting is defined and set to 'true').