Created Base Plugin Settings (markdown)

Base-Plugin-Settings.md

@@ -0,0 +1,91 @@
+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 skylands worlds use the **skylands** 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 skylands will use **skylands_XXX**).  See [[HD Map Configuration]] for more details.
+
+* _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.
+
+* _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.
+
+    + _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)
+
+* _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.
+
+* _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.
+
+* _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 boolean, is used to optionally pin the sidebar menu open by default (true).  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.
+
+* _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.
+
+* _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.
+
+* _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.