Component Configuration

The interface for Dynmap is defined via a set of components. Not all components can be enabled at once, and some are required. Details on the defined compnents, and their attributes, are in the following sections.

Core Client Components

The following components defined the core of the client's interface with the Dynmap server. The Client Configuration Component, and at least one of the Client Update Components is required for any client functionality.

Client Configuration Component

This component is defined by the following lines in the components section:

  - class: org.dynmap.ClientConfigurationComponent

This component is required, and has no settings.

Internal Client Update Component

This component defines the primary interface for the web client via Dynmap's internal web server (which must be enabled for this component to function). It defines URLs for the client to use under the http://address:port/up/ path, including both fetching configuration data, and fetching map updates, player status and chat messages. The component is configured via the following lines in the components section:

  - class: org.dynmap.InternalClientUpdateComponent
    sendhealth: true
    sendposition: true
    allowwebchat: true
    webchat-interval: 5
    hidewebchatip: false
    trustclientname: false
    use-player-login-ip: true
    require-player-login-ip: false
    block-banned-player-chat: true
    webchat-requires-login: false
    webchat-permissions: false
    includehiddenplayers: false
    hideifshadow: 15
    hideifundercover: 15
    hideifsneaking: false
    protected-player-info: false

The settings are defined as follows:

• sendhealth : this controls whether or not the health data for players is reported to the web client. If it is disabled, other components that report player health will not have the needed data to do so, but player health information is also safe from being inspected. If enabled, health information may still be hidden for players located on specific worlds via the sendhealth: false setting on those worlds.

• sendpostiion : this controls whether or not the position data for players is reported to the web client. If it is disabled, other components that report position will not have the needed data to do so, but player position information is also safe from being inspected. If enabled, position information may still be hidden for players located on specific worlds via the sendposition: false setting on those worlds.

• allowwebchat : this setting controls whether or not the interface to allow chat messages to be sent from the web client to the server is enabled. If false, no web messages may be sent from the client.

• webchat-interval : this controls the minimum period, in seconds, between consecutive chat messages from a given web client.

• hidewebchatip : if set to true, this causes web chat messages to be reported via generic names versus the IP address of the sender.

• trustclientname : if set to true, this causes the hostname/IP reported by the web client (which may be falsified) to be reported as the sender's address (versus using the address seen by the web server).

• use-player-login-ip : if set to true, web chat messages will be matched with current or previous player IDs having connected from the same IP address - if a match is found, the most recent player ID is used to identify the sender of the web chat message. Default is true (0.29 or later)

• require-player-login-ip : if use-player-login-ip is true, and this setting is true, web chat messages not matching a current or previous player connection address will be ignored. Default is false (0.29 or later).

• block-banned-player-chat : if use-player-login-ip is true, and this setting is true, web chat messages that match a previous player address of a currently banned player will be ignored. Default is true (0.29 or later). Note: does not work with plugins that implement their own ban independent of Bukkit/Minecraft's ban (currently, this is true of CommandBook).

• webchat-requires-login : if login-enabled is true, and this setting is trye, web chat messages can only be sent from web users that have successfully logged in.

• webchat-permissions : if defined and set to 'true', web chat requests tied to players (via login or ID-by-IP) will be checked for the dynmap.webchat permission, with those not possessing the permission being denied the right to send. This requires a permission system that supports reading permissions for offline players - currently PermissionsEx and bPermissions - in order to work for web users that are not currently logged in using the Minecraft client, as well.

• includehiddenplayers : if set to true, players that are hidden (via the /dynmap hide command) will be reported to the UI as online, but with their position, health, and messages still hidden. They will appear in the player list.

• hideifshadow : if set to a value below 15, each player's position and health are hidden if the light level of the current location of the player is at or below the given value (0=total darkness, 4=under sky at night, 15=full daylight).

• hideifundercover : if set to a value below 15, each player's position and health are hidden if the current position of the player is under cover. Due to a current Bukkit limitation (pending acceptance of a pull request we issued), any block will obstruct the view of the player (once updated, this will shift to be based on the relative shadow level of the location - corresponding to how much the location would be in shadow during full daylight).

• hideifsneaking : if set to true, players that are sneaking will be hidden.

• protected-player-info : if set to true, access to player position and health information is protected. Players without the dynmap.playermarkers.seeall permission (operators have this by default) will only see their own player marker, while those with the permission will see all player positions. If this setting is not provided, or is false, all player position and health information is available to all map viewers.

JSON File Client Update Component

The alternative to using the internal web server is for all communications between Dynmap and the web client to be done via files served through an external web server. As this is done with files formatted using JSON (JavaScript Object Notation), this mode of operation is often referred to as "JSON File Mode". This mode allows the internal web server to be disabled, and is the alternative to using the Internal Client Update Component (only one of them may be enabled at a time). The component is defined by the following lines in the components section:

  - class: org.dynmap.JsonFileClientUpdateComponent
    writeinterval: 1
    sendhealth: true
    sendposition: true
    allowwebchat: false
    webchat-interval: 5
    hidewebchatip: false
    trustclientname: false
    use-player-login-ip: true
    require-player-login-ip: false
    block-banned-player-chat: true
    webchat-requires-login: false
    webchat-permissions: false
    includehiddenplayers: false
    hideifshadow: 15
    hideifundercover: 15
    hideifsneaking: false
    protected-player-info: false

The definitions of the attributes are the same as the corresponding attributes in the Internal Client Update Component. The additional attributes are as follows:

• writeinterval : this is the period, in seconds, used by the component for writing updated configuration and map update files to the webpath/standalone directory. These are the files loaded by the web client via the external web server to receive the map configuration, as well as notifications of map updates, player position and health data, and chat messages.

Markers Component

This component, added in v0.22, provides built-in support for map markers, both through the /dmarker commands and through an API published for use by other plugins. The component is configured via the following lines in the components section:

  - class: org.dynmap.MarkersComponent
    type: markers
    showlabel: false
    enablesigns: false
    showspawn: false
    spawnicon: world
    spawnlabel: "Spawn"
    showofflineplayers: false
    offlinelabel: "Offline"
    offlineicon: offlineuser
    offlinehidebydefault: true
    offlineminzoom: 0
    maxofflinetime: 30
    showspawnbeds: false
    spawnbedlabel: "Spawn Beds"
    spawnbedicon: "bed"
    spawnbedhidebydefault: true
    spawnbedminzoom: 0
    spawnbedformat: "%name%'s bed"

The settings for the component include the following:

• showlabel : if defined and set to true, this causes the labels for map markers to be shown all the time, versus only being shown when the user's mouse is hovering over the icon.

• enablesigns : If defined and set to true, this enables support for defining markers using signs. If enabled, and if the player has the dynmap.marker.sign privilege, a player can make a marker by creating a sign with '[dynmap]' as the first line, with the label being derived from the first non-blank line after that (that is not a setting). The icon will be the 'sign' icon, unless one of the lines is 'icon:'. The marker set for the marker will be the default 'markers' set, unless one of the lines is 'set:'. Once accepted, the '[dynmap]' line and any settings lines will be blanked, leaving the sign with the label line and any remaining lines. Destroying the sign will delete the corresponding marker.

• showspawn : if defined and set to true, this causes the spawn points of each world to be shown with an appropriate marker (the default being the 'world' marker) and label (the default being "Spawn").

• spawnicon : if defined, provides the ID of the icon to use for the spawn points (if showspawn is true). Default is 'world'.

• spawnlabel : if defined, provides the label for the spawn point markers (if showspawn is true). Default is "Spawn".

• showofflineplayers : if defined and set to true, a marker layer is defined to show the positions of offline players (markers will be added as players log off).

• offlinelabel : Label used for the offline player marker layer - default is 'Offline'

• offlineicon : Name of the marker icon used for offline players - default is 'offlineuser'

• offlinehidebydefault : if defined and set true, offline marker layer is hidden by default. Default is 'true'.

• offlineminzoom : if set to non-zero, this specifies the minimum zoom in level before offline player markers are displayed.

• maxofflinetime : if set above zero, this specifies the number of minutes after a player logs off before their offline icon should be removed (<= 0 means never). All offline player markers are reset on a server restart, independent of this setting.

• showspawnbeds : If defined and set to true, a marker layer is defined to show the positions of the online players' spawn beds (markers will be removed when players log off).

• spawnbedlabel : Label for player spawn bed marker layer, if enabled. Default is "Spawn Beds".

• spawnbedicon : Icon to use for any spawn bed markers. Default is 'bed' marker.

• spawnbedhidebydefault : If true, spawn bed marker layer will be hidden, by default.

• spawnbedminzoom : If set to non-zero, this specifies the minimum zoom in level before spawn bed markers are displayed.

Server-Side Chat Components

These components control the server-side implementation of chat, including the sending of chat messages from the server to the client, as well as particulars of how chat messages from the client to the server are delivered to players on the server. Only one of these components should be defined at a time.

Simple Chat Component

This component implements access to the standard Bukkit/Minecraft server's chat channel. When active, all chat messages are shared with the web client, and all messages received from the web client are sent to all players on the server (as well as all other web clients). This component is configured via the following lines in the components section:

  - class: org.dynmap.SimpleWebChatComponent
    allowchat: true

The settings for the component include:

• allowchat : if enabled, this setting determines if chat messages on the server are to be sent to the web clients. If set to 'false', no chat messages are sent to the web clients.

HeroChat Chat Component (Deprecated - not functional with HeroChat 5)

The HeroChat plugin implements channels and other behaviors that require special treatment. This component interfaces with HeroChat, and allows the selection of which HeroChat channels have their messages reported to the web clients, and which channel messages from the web clients are reported on. This component is configured via the following lines in the components section:

  - class: org.dynmap.herochat.HeroWebChatComponent
    herochatwebchannel: Global
    herochatchannels:
      - Global

The settings for the component are as follows:

• herochatwebchannel : this is the name of the HeroChat channel that will be used for any chat messages received from the web clients. Default value is 'Global'

• herochatchannels : this is the list of HeroChat channel names that will be monitored for chat messages, which will then be shared with the web clients. Zero or more channels may be listed. The default is a single channel list containing 'Global'.

Client-Side Chat Components

These components control the behavior and availability of the components of the web client used to support sending and receiving of chat messages. These components depend upon the corresponding server-side components being enabled and allowing the requested functions. The components can be defined individually or in any combination.

Chat Client Component

This component enables the input field for chat messages, allowing the users to enter and send chat messages to the server from the web client. It is defined by the following lines:

  - class: org.dynmap.ClientComponent
    type: chat
    allowurlname: false

The component supports the following settings:

• allowurlname : if true (and if trustclientname is true in the corresponding ClientUpdateComponent), the user of the web console can supply a chat name using the chatname URL parameter.

Chat Balloon Client Component

This component implements support for pop-up balloon messages, with the balloon being placed above the location of the sending player on the map, if any. The component is defined via the following lines in the components section:

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

The component supports the following settings:

• focuschatballoons : if enabled, this causes the map to pan to the chat balloon, if it is not currently visible on the map.

Note that placement of the word balloons requires that the position data for the speaking player is known, which may not be the case if sendposition: false has been set for the player's current world, or globally via the active Client Update Component.

Chat Box Client Component

This implements the box for viewing chat messages received from players on the server, as well as from other web clients. The component is defined via the following lines in the components section:

  - class: org.dynmap.ClientComponent
    type: chatbox
    showplayerfaces: true
    messagettl: 5
    scrollback: 100
    sendbutton: false

The settings for this component are as follows:

• showplayerfaces : if enabled, the face icons for the player that sent a given chat message will be shown next to the message.

• messagettl : this controls the number of seconds that a received chat message is shown on the screen before fading. If scrollback is defined, this setting is ignored.

• scrollback : if defined, this specifies the number of messages to keep in the scrollable message list. If specified, messages will not age out (messagettl is ignored) and will only be dropped as the number of messages exceeds the scrollback count.

• sendbutton : if defined and set to true, this causes a send button to appear on the web UI, allowing messages to be sent without requiring the pressing of the return key.

Map Controls Components

These define additional map content, such as player markers, clocks, logos, etc. Any set of these components can be defined.

Player Markers Component

This component is used to show player positions and names as markers on the displayed map. The player's position can only be shown if it is available (see the sendposition setting, above). The component is defined by the following lines in the components section:

  - class: org.dynmap.ClientComponent
    type: playermarkers
    showplayerfaces: true
    showplayerhealth: true
    showplayerbody: false
    smallplayerfaces: false
    hidebydefault: false
    layerprio: 0
    label: "Players"

The settings for the component include the following:

• showplayerfaces : if enabled, this causes the client to attempt to load the custom skin for the player (if any) and to show the face portion of that skin as the icon for the player. Otherwise, a small generic marker is shown instead.

• showplayerhealth : if enabled, the client will attempt to show health and armor attributes for the player, as two rows of small icons below the player's name. This requires that the player's health information be available (see sendhealth, above).

• smallplayerfaces : if enabled, player faces are shown (assuming showplayerfaces is true), but at 1/2 the normal size (equivalent to the small generic markers used when showplayerfaces is false).

• showplayerbody : if enabled, whole body icons will be show instead of just faces. Only applicable if showplayerfaces is true and smallplayerfaces is false.

• hidebydefault : this optional parameter, if defined and set to true, changes the default visibility state for the map layer with the player markers to be hidden. The layer can still be made visible with the layer control on the web client UI.

• layerprio : this optional parameter provides an ordering weight for the layer in the layer selection control, which orders from lowest to highest layerprio (and then alphabetically for equal priority layers). Default is 0.

• label : this optional parameter provides the label used for the layer selection control for this layer set. Default is 'Players'.

Digital Clock Component

This is used to display a simple digital clock, corresponding to the time on the world being displayed. The component is defined by the following lines in the components section:

  - class: org.dynmap.ClientComponent
    type: digitalclock

Only one clock component can be enabled at a time.

Time Of Day Clock Component

This is a more sophisticated clock component, showing day and night via sun and moon icons that rise and set to match the time in the world being shown. The component is defined via the following lines in the components section:

  - class: org.dynmap.ClientComponent
    type: timeofdayclock
    showdigitalclock: true
    showweather: true

The settings for the component include the following:

• showdigitalclock : if enabled, the digital clock is displayed (in addition to the sun and moon display)

• showweather : if enabled, an icon is shown to indicate weather (rain, thunder) on the world being shown by the map.

Coord Component

This component is used to show the world coordinates corresponding to the position of the mouse pointer. The component is defined via the following lines in the components section:

   - class: org.dynmap.ClientComponent
     type: coord
     label: "Location"
     hidey: false
     show-mcr: false

The settings for the component are as follows:

• label : this allows control of the label used on the control presenting the coordiates. Default is 'x,y,z'.

• hidey : this option, if defined and set to true, makes the coordinate control only show X,Z coordinates.

• show-mcr : this option, if defined and set to true, causes the display of the Mincraft Region file ID for the current location.

Logo Component

This component is used to allow an optional logo and link to be shown on the map. The component is defined via the following lines in the components section:

   - class: org.dynmap.ClientComponent
     type: logo
     text: "Dynmap"
     linkurl: "http://forums.bukkit.org/threads/dynmap.489/"

The settings for the component are as follows:

• text : the label shown for the logo

• linkurl : the URL associated with the link tied to the displayed label

Link Component

This component is used to provide a 'link to' button on the web UI. This button, when clicked, will navigate the view to a URL with all the needed settings to preserve the world, map, zoom, and coordinates of the current view - allowing a view to be shared, bookmarked, or otherwise linked. The component is defined via the following lines in the components section:

   - class: org.dynmap.ClientComponent
     type: link

There are no settings currently defined.