World and template settings

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
    hiddenlimits:
      - x0: 100
        z0: 0
        x1: 200
        z1: 0
    hidestyle: stone
    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. To disable worlds automatically, the enabled setting has to be set to false in the template that is selected by the deftemplatesuffix in configuration.txt

• 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. As of 1.5-alpha-3, circular areas can also be defined, by providing an x, z value for the center and a r value for the radius, in blocks.

• hiddenlimits : if defined, this list of rectangles that are the opposite of 'visibilitylimits' - they define specific areas of the world to be hidden (rendered based on the hidestyle setting, below). If both 'visibilitylimits' and 'hiddenlimits' are defined, the 'visibilitylimits' are applied first (determining which areas are visible), and then the 'hiddenlimits' are used to further restrict that. Each rectangle consists of two coordinate pairs - x0, z0, and x1, z1. As of 1.5-alpha-3, circular areas can also be defined, by providing an x, z value for the center and a r value for the radius, in blocks.

• hidestyle : If the visibilitylimits and/or hiddenlimits settings have 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.

• 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. If not defined, the center defaults to the spawn point for the given world.

• 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 enables 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.

• showborder : if defined, the showborder boolean toggles whether a red outline should appear on the map where the world border is located.