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.17 this section can be left empty: Dynmap will automatically show all worlds in its map.

This is where the templates come into play. By default there are two templates: normal and nether. The template that is chosen by default for a certain world depends on the environment of the world. Look for the individual properties of the templates to see what is possible to change.

Next to the templates we also have a worlds section in the configuration. 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 and specify for those worlds in particular the name of that template.

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

Here world and nether both use the custom 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 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.