Created World and template settings (markdown)

World-and-template-settings.md

@@ -0,0 +1,74 @@
+There are an extensive set of configurable settings for controlling the map and interface definitions for the worlds on a user's server.  Nearly all of these settings are also settable on templates - which is appropriate, since templates are essentially a collection of settings used to define any settings not defined for the worlds that use them.
+
+Logically, any defined world will have a default set of settings, derived from the template that is associated with its environment type (normal, nether, skylands) - the settings are inherited from the template of the same name as the environment, by default.  If the **deftemplatesuffix** is defined, the name of the template inherited from is modified by appending a hyphen ('-') and the value of the setting.  So, setting **deftemplatesuffix** to **hires** causes the template automatically used by a normal world to be **normal-hires**, and for nether worlds to be **nether-hires**.
+
+Beyond the values inherited from the template, settings for a given world can always be provided by defining a section for the world in the **worlds:** section (in **worlds.txt**, or in **configuration.txt**).  When a section exists for a given world, any setting provided there will override any corresponding setting inherited from the world's template.
+
+With the exception of the world's **name** and **maps**, all other world settings are optional and have defined defaults, and the **maps** are typically provided through templates.  Consequently, a world definition under the **worlds:** section can consist of nothing but the world's name:
+
+    worlds:
+      - name: world1
+      - name: world2
+
+This can be used to control the order of the worlds, as defined worlds are always listed in their order of definition, and automatically selected worlds are listed after those.
+
+An example of a more comprehensive set of world settings are shown below:
+
+    worlds:
+      - name: world
+        title: "My Great World"
+        enabled: true
+        template: mycustomtemplate
+        sendposition: true
+        sendhealth: true
+        fullrenderlocations:
+          - x: 100
+            y: 64
+            z: 2000
+        visibilitylimits:
+          - x0: -1000
+            z0: -1000
+            x1: 1000
+            z1: 1000
+        hidestyle: stone
+        autogenerate-to-visibilitylimits: none
+        center:
+          x: 0
+          y: 64
+          z: 0
+        bigworld: false
+        extrazoomout: 0
+        maps:
+          - class: org.dynmap.flat.FlatMap
+          ....
+
+The available settings are defined as follows:
+
+- _name_ : this defines the name of the world within Bukkit, and must be unique.  This can not be inherited from a template.
+
+- _title_ : if defined, this string is used as a human-friendly label for the world.  The default value is blank.
+
+- _enabled_ : if defined, this allows mapping for a given world to be enabled (by setting **true**) or disabled (by setting **false**).  All worlds are enabled by default, so defining a **worlds** entry for a world and setting _enabled_ to **false** is the only way to prevent a world from being displayed and mapped.
+
+- _template_ : if defined, this overrides the name of the template used to provide the default settings for the world.  If not set, the default is based on the world's environment (normal, nether, or skylands), with a '-' and the **deftemplatesuffix** value added if **deftemplatesuffix** is defined.  This value cannot be inherited from a template.
+
+- _sendposition_ : if defined and set to **false**, this allows the option to have the position information for any players located on this world to be hidden on the UI, even if such information is enabled otherwise.  Setting this attribute to **true** will NOT cause player information to be displayed if the global _sendposition_ setting is **false**.  If not defined, this setting defaults to **true**.
+
+- _sendhealth_ : if defined and set to **false**, this allows the option to have the armor and health information for any players located on this world to be hidden on the UI, even if such information is enabled otherwise.  Setting this attribute to **true** will NOT cause player information to be displayed if the global _sendhealth_ setting is **false**.  If not defined, this setting defaults to **true**.
+
+- _fullrenderlocations_ : if defined, this list of world coordinates (each consisting of an **x**, **y**, and **z** coordinate) defines a set of additional locations (beyond x=0, y=64, z=0, or the player's current location, if a **/dynmap fullrender** command is issued by an in-game player) to be used to seed a full-render.  Logically, fullrender is implemented like a _flood fill_ in a paint program - if a map has gaps in its areas of defined chunks, such as can happen if maps are explored via teleporting or portals, a fullrender seeded from one point may not reach all the patches of the world that have been generated: adding example locations within the other patches to the _fullrenderlocations_ list will cause those patches to be rendered, as well.
+
+- _visibilitylimits_ : if defined, this list of rectangles can be used to restrict the area of the world to be rendered: areas outside of these rectangles will not be rendered with accurate map data, but instead some form of filler will be used (depending on the _hidestyle_ setting, below).  If the list is empty (the default), no limits are implemented, and maps will be rendered to the edge of the generated chunks for the world.  Each rectangle consists of two coordinate pairs - **x0**, **z0**, and **x1**, **z1**.
+
+- _hidestyle_ : If the _visibilitylimits_ setting has restricted the visible areas of a world, the _hidestyle_ setting is used to control how the chunks of map data being hidden are presented.  3 settings are supported: **stone**, which causes a stone plain to fill the hidden areas; **ocean**, which causes a deep ocean to fill the hidden areas;  or **air**, which causes the hidden area to be empty (like the edge of the generated portion of the world map).  The default value is **stone**.
+
+- _autogenerate-to-visibilitylimits_ : If the _visbilitylimits_ setting has restricted the visible area of the world, this setting can be used to cause Dynmap to fill in the ungenerated portions of the map within the visible areas.  The settings include **none** (do nothing - the default), **map-only** (generate the data needed to draw the map, but don't cause the chunks to be permanently generated), or **permanent** (generate and save the chunks for any ungenerated portion of the world).
+
+- _center_ : If defined, this provides the default center-of-focus for the view of the maps of this world.  The coordinate includes the **x**, **y** and **z** coordinate of the center point, in world coordinates.
+
+- _bigworld_ : If defined, this enables the use by the FlatMap and KzedMap map types of an alternate file system structure, better suited to use by large worlds that may have tens or even hundreds of thousands of tiles.  HDMaps always use this format, and are not affected by this settings.  The default value is **false**, while a value of **true** enabled the alternate layout.  If the setting is changed, a **/dynmap fullrender** will be needed to initialize the new layout.
+
+- _extrazoomout_ : If defined, this specifies how many additional levels of _zoom out_ the maps for this world should have, beyond their default.  This results in both offering more levels of zoom on the map viewer, and in additional levels of map tiles being generated (based on the original tiles generated for the maps): each level is 2 x 2 the scale of the previous level, so 4 tiles on one level become 1 tile with less resolution on the next.  Enabling this setting, by setting the value to an integer above 0, will add from 25% to 33% to the number of tile files, and total disk space used, by the maps for the given world, but will allow easier navigation of mid-sized to large worlds.  The default value is **0** (no extra zoom out).
+
+- _maps_ : if defined, the _maps_ section provides all the definitions for the maps to be rendered for the world, in the order that they are presented on the map viewer.  If defined in a world's section in **worlds:**, any map definitions provided by the world's template are replaced.  For details on map definition, see [[Map Configuration]] and [[HD Map Configuration]].
+