Configuration

Here we'll describe how the configuration is structured and how to edit the configuration.

The configuration in the file plugins/dynmap/configuration.txt which is in YAML format. It has a hierarchical structure that is defined using indentation. The indentation in the configuration may NOT contain any tabs, only spaces. This also means that you need to be sure to put the correct number of spaces in front of configuration-lines.

Just as a reference, you can view the default configuration here: https://github.com/webbukkit/dynmap/blob/recommended/src/main/resources/configuration.txt.

The configuration consists of 4 parts in the following order: components, global settings, world-templates and worlds. The global settings change behaviour of the rendering and the (internal) webserver of Dynmap. It should be obvious how these work. An example of a global setting is:

# How often a tile gets rendered (in seconds).
renderinterval: 1

Note: As of v0.20, the default configuration.txt file has been split, with the templates: section being moved to the templates/ directory and the worlds: section being moved to the worlds.txt file. Users are NOT required to change their existing configuration.txt - templates or worlds defined in configuration.txt are still processed, and templates found there supersede those of the same name from the templates/ directory. It is recommended the existing users, at their convenience, move their worlds: section (if they have one defined) from configuration.txt to worlds.txt, to prevent future impacts on that configuration due to future updates of configuration.txt. Likewise, it is suggested that existing users move their templates: section from configuration.txt to a new file, templates/custom-templates.txt.

Components

The components-section looks a like:

components:
  - class: org.dynmap.ClientConfigurationComponent
  
  - class: org.dynmap.InternalClientUpdateComponent
    sendhealth: true
    allowwebchat: true
    webchat-interval: 5
...

Each component can be thought of as an separate feature of Dynmap, which can be disabled and enabled individually. Some components depend on others, but we won't get into that. Each component starts in the configuration with a - class: ... followed by the properties of that component.

As an example we're going to disable the component that handles chat-balloons. This component looks like this:

...
  - class: org.dynmap.ClientComponent
    type: chatballoon
    focuschatballoons: false
...

We can disable it by just deleting these lines, but a safer way is to comment them. For this example I've added the lines before and after the component to give a better impression:

...
  - class: org.dynmap.ClientComponent
    type: chat
  #- class: org.dynmap.ClientComponent
  #  type: chatballoon
  #  focuschatballoons: false
  - class: org.dynmap.ClientComponent
    type: chatbox
    showplayerfaces: true
    messagettl: 5
...

Be sure to have still the correct number of spaces in front of the #. After saving the configuration, reloading Dynmap and refreshing the browser, chat balloons won't pop up anymore. The same method can be used to enable already disabled components.

Worlds and templates

In the configuration you'll also see a worlds section (since 0.20, this is found in the worlds.txt file; previously, it was found near the bottom of the configuration,txt file). This section can be left empty - Dynmap will automatically find all worlds defined for a server, and provide them with a default map configuration, based on using templates, as defined in the templates: section. Since 0.20, the templates definitions have been moved from configuration.txt into separate files found in the templates/ directory, but otherwise function as they have previously.

Templates

By default there are three templates: normal, nether and skylands. The template that is chosen for a certain world depends on the environment of the world - normal for normal worlds, nether for nether worlds, skylands for skyland worlds. As of 0.20, these definitions are found in files under the templates/ directory, with filenames corresponding to the template's name: templates/normal.txt, templates/nether.txt, and templates/skylands.txt, respectively.

In 0.20, the names of the templates chosen can be modified by using the deftemplatesuffix setting in configuration.txt. If defined, the name of the template used for a world with a given environment will have a hyphen followed by the value of the deftemplatesuffix setting added: so, setting deftemplatessuffix to hires causes the template normal-hires to be used for normal worlds, nether-hires to be used for nether worlds, and skylands-hires to be used for skylands worlds. This allows dynmap (and other users) to supply matched "sets" of templates, with a common suffix, that can be easily selected using the deftemplatessuffix setting. In 0.20, 3 sets of templates are provided:

• the default (normal,nether,skylands)

• lowres template set (normal-lowres, nether-lowres, skylands-lowres - which provide HD maps with the 'lowres' resolution - about 2x the default maps)

• hires template set (normal-hires, nether-hires, skylands-hires - which provide HD surface maps with the 'hires' resolution - about 8x the default maps - and 'lowres' versions of the flat and cave maps)

In all cases, the template definition can be found in the file under the templates/ directory with the corresponding name, plus .txt (e.g. normal-hires is found in templates/normal-hires.txt).

Worlds

Next to the templates we also have a worlds section in the configuration. As of 0.20, the preferred location for this section is the worlds.txt file. Here we can specify options for each individual world. We'll describe the uses by examples.

Basically each world has a few default values. title is set to the name of the world, template is set to the environment of the world and enabled is by default true (the meaning of these values are explained below). The template of the world can override these values, but the properties in the world-section can in turn override the values of the template.

If you have 3 worlds with the names world, nether and alternative, and you want to show them in a particular order, you can put the following in your configuration:

worlds:
  - name: world
  - name: alternative
  - name: nether

So that they are ordered like world, alternative, nether.

To change the title of a certain world that is shown on the map, you can add a title property for that world:

worlds:
  - name: world
    title: "My Super Awesome World"
  - name: alternative
  - name: nether

Of course you can do this for all your worlds.

If you want to disable a certain world, for example the world alternative, you can do so by adding the property enable: false:

worlds:
  - name: world
    title: "My Super Awesome World"
  - name: alternative
    enabled: false
  - name: nether

You can also use this property in your templates to (for example) disable all worlds of a certain environment.

If you want to change some of the properties for one specific world, you can do so specifying that property. This includes the maps: property, so you can specify the maps for a specific world:

  - name: world
    title: "My Super Awesome World"
    center:
      x: 100
      y: 64
      z: 0
    maps:
      - class: org.dynmap.flat.FlatMap
        name: flat
        title: "Flat"
        prefix: flat
        colorscheme: default

This will, for this particular world, set the center of the world to (100,64,0) and shows only flatmap in the sidebar.

Finally if you have multiple worlds that have the same configuration in common, you can add a template to the templates: section (or, better yet, as a custom template file under the templates directory) and specify for those worlds in particular the name of that template.

templates:
  mycustomtemplate:
    enabled: true
    maps:
      - class: org.dynmap.flat.FlatMap
        name: flat
        title: "Flat"
        prefix: flat
        colorscheme: ovocean
...
worlds:
  - name: world
    template: mycustomtemplate
  - name: nether
    template: mycustomtemplate
  - name: alternative

Here world and nether both use the mycustomtemplate template, but alternative will still use the normal template (since alternative has an normal environment in this example).

As you can see above, for each FlatMap or KzedMap map, a certain colorscheme can be set. The colorschemes can be found in plugins/dynmap/colorschemes/, as seen here https://github.com/webbukkit/dynmap/tree/recommended/colorschemes. An overview of how these look like can be found here Color Schemes.

As of 0.20, a new type of map definition has been provided - the HDMap. This map type, besides supporting higher resolution map rendering and use of texture packs, also supports all existing FlatMap and KzedMap features, but with more flexibility (allowing customized direction of view, angle of view, scale, etc). For details on configuring HDMaps, see HD Map Configuration.