Using markers - webbukkit/dynmap GitHub Wiki

Dynmap supports mechanisms for adding content to maps, above what is rendered by the maps. This content is collectively referred to as Markers, and consist of markers (marker icons), marker areas, and marker poly-lines.

Markers are collected and organized as collections, referred to as Marker Sets. Each Marker Set is a labelled layer, selectable using the web UIs layer selector. Every marker is contained within a specific marker set. By default, there is always at least one marker set, labelled Markers, that will be used to contain any markers that are not specifically assigned to another marker set. Deleting a marker set will delete all markers within the set.

New marker sets can be created using the /dmarker addset <markerset-label> or /dmarker addset id:<markerset-id> commands. Additional parameters can be used to refine the set's behavior: prio:<N> is used to control the order of the layer in the layer control, relative to other sets; hide:<true|false> is used to control whether the set is visible (checked) or hidden (unchecked) by default; minzoom:<N> is used to make the markers in the set hidden until a specific zoom level is selected.

Settings on existing marker sets can be altered using the /dmarker updateset <markerset-label> or /dmarker updateset id:<markerset-id> commands, with prio:<N>, hide:<true|false> or newlabel:<new-label> as parameters.

As of 0.32, the setting showlabels:<true|false|null> is supported. This setting, when true or false, enables or disables the visibility of marker labels (disabled visibility causes labels to only show when the mouse cursor is hovering over the marker). The value null uses the global default behavior (defined by the showlabels setting in the markers component in configuration.txt.

Marker sets (except for the default marker set, Markers) can be deleted using the /dmarker deleteset <markerset-label> or /dmarker deleteset id:<markerset-id> commands.

Markers are the most common map markers - simple icons with an associated label and/or an associated description popup. Each marker has a defined location in world coordinates (X, Y, Z and a world ID), a marker icon ID, a label, and an optional description. The marker icon ID can be one of the standard marker IDs (shown at the bottom of this page), or can correspond to an installed icon (see Marker Icons section, below).

Markers can be added one of a couple of ways:

• /dmarker add <marker-label> icon:<icon-id> set:<markerset-id> - this must be issued by a logged-in player, and will cause a marker to be defined at the player's current location. If set is not provided, the marker will be created in the default marker set, Markers. If icon is not defined, the default marker icon is used (default, a house).

• /dmarker add id:<marker-id> <marker-label> icon:<icon-id> set:<markerset-id> x:<x-coord> y:<y-coord> z:<z-coord> world:<Worldname> - Same as above, except that the unique ID of the marker, the position and world of the marker is specified, which makes it also executable from console.

• Using a sign: If the enablesigns setting on the markers component is true, users with the appropriate privilege (dynmap.marker.sign) can create markers using specially labelled signs. To use these, the first line of the sign MUST be [dynmap]. After that, any non-blank line will be included in the label of the marker, except for lines formatted as set:<markerset-id> (which allows the marker to be added to a specific marker set) or icon:<icon-id> (which allows the marker to be set to use a specific icon - if not specified, the icon sign is used). If the marker is successfully created, the sign's text will erase the [dynmap], set: and icon: lines. If the sign is later deleted, the corresponding map marker is deleted.

Once created, markers can be edited using one of a couple of commands:

• /dmarker movehere <marker-label> set:<markerset-id> or /dmarker movehere id:<marker-id> set:<markerset-id>: This will move the existing marker to the player's current location. Note: the markerset-id is required to select a marker not in the default marker set (markers).

• /dmarker update <marker-label> set:<markerset-id> icon:<icon-id> newlabel:<new-label> or /dmarker update id:<marker-id> set:<markerset-id> icon:<icon-id> newlabel:<new-label>. Note: the markerset-id is required to select a marker not in the default marker set (markers) - the marker set ID is not editable.

To add a description to a marker, first clear any existing description using /dmarker resetdesc id:<marker-id> set:<set-id> and then append the new description using /dmarker appenddesc id:<id> set:<set-id> desc:"<marker-description>". make sure that the desc field is a string using " " around your given text.

Markers can be deleted using the /dmarker delete <marker-label> set:<markerset-id> or /dmarker delete id:<marker-id> set:<markerset-id> command.

Existing marker sets, and their attributes, can be shown using the /dmarker listsets command.

Existing markers, and their attributes, can be shown using the /dmarker list set:<markerset-id> command.

Marker Icons are image resources used to provide the images for markers. Dynmap supplies a number of standard marker icons, shown below, that are always present and defined, and are not deletable. The list of availabile icons can be found by running the /dmarker icons command.

New marker icons can be installed by doing the following:

• Copy the image file, in PNG format, to the bukkit server's file system. The image in the file should be 8x8, 16x16 or 32x32 pixels in size.

• Run the command /dmarker addicon id:<icon-id> <icon-label> file:<path-to-image-file> - if successful, the image file will be imported (so it doesn't need to be left where it was first copied).

To update the image for an existing icon, run the /dmarker updateicon id:<icon-id> newlabel:<new-label> file:<path-to-image-file>.

To delete an existing image, run the /dmarker deleteicon id:<icon-id>.

Area markers are used to place 2-D or 3-D outlines on the world maps. The area defined by an area marker is defined by a sequence of 2 or more X,Z coordinates, defining a rectangle (if 2 points, they are opposite corners of the rectangle) or a polygon (if 3 or more points, they define the ordered sequence of points for the polygon, with the last point connecting to the first). Optionally, the minimum and maximum Y coordinates can be supplied, to extend the 2-D shape into a 3-D volume (flat on the top and bottom).

The appearance of the edges of the outline can be controlled by setting the color attribute (HEX: RRGGBB), line weight (0-N), and opacity (0.0-1.0). The appearance of the filled area within the outlines can be controled by setting the fill color attribute (HEX: RRGGBB), and fill opacity (0.0-1.0).

To create an area, a list of corners needs to be supplied. Corners can be entered as follows:

• Running /dmarker addcorner to add the player's current position as a corner.

• Running /dmarker addcorner <x> <y> <z> or /dmarker addcorner <x> <y> <z> <world> to add a specific coordinate as a corner.

If needed, the corner list can be reset using the /dmarker clearcorners.

Once all the corners are entered, an area marker can be created using the /dmarker addarea <area-label> set:<markerset-id> or /dmarker addarea id:<area-id> <area-label> set:<markerset-id> commands. Additional attributes can be set with these commands, or later updated using the /dmarker updatearea id:<area-id> set:<markerset-id> or /dmarker updatearea <area-label> set:<markerset-id> newset:<new-markerset-id> command. These settings include:

• color - outline color (color:RRGGBB)

• fillcolor - fill color (within the outlines) (fillcolor:RRGGBB)

• opacity - Opacity of the outline strokes (0.0 = transparent, 1.0 = solid)

• fillopacity - Opacity of the filled color areas (0.0 = transparent, 1.0 = solid)

• weight - Stroke weight of outline (0=minimum, higher=thicker)

• ytop - Y coordinate of the top of the area (default=64)

• ybottom - Y coordinate of the bottom of the area (default=64)

Note: The corners in an existing area cannot currently be updated - delete the existing area and add a new area to update these. Also, the corner list is reset after they are used to create a new area using the /dmarker addarea command.

To delete an area marker, use the /dmarker deletearea id:<area-id> set:<markerset-id> command.

Existing areas, and their attributes, can be shown using the /dmarker listareas set:<markerset-id> command.

Circle markers are used to place 2-D circular (or elliptical) outlines on the world maps. The area defined by a circle marker is defined by a center point (x, y, z) and either a radius (for a circle, via radius setting) or an X vs Z radius (for an ellipse, via radiusx and radiusz setting).

The appearance of the edges of the outline can be controlled by setting the color attribute (HEX: RRGGBB), line weight (0-N), and opacity (0.0-1.0). The appearance of the filled area within the outlines can be controled by setting the fill color attribute (HEX: RRGGBB), and fill opacity (0.0-1.0).

A circle marker can be created using the /dmarker addcircle <circle-label> set:<markerset-id> or /dmarker addcircle id:<circle-id> <circle-label> set:<markerset-id> commands. Additional attributes can be set with these commands, or later updated using the /dmarker updatecircle id:<circle-id> set:<markerset-id> or /dmarker updatecircle <circle-label> set:<markerset-id> command. These settings include:

• x - X coordinate of center (default is current location of player issuing command)

• y - Y coordinate of center (default is current location of player issuing command)

• z - Z coordinate of center (default is current location of player issuing command)

• radius - radius of circle (default is 1)

• radiusx - radius of ellipse on X axis (default is 1)

• radiusz - radius of ellipse on Z axis (default is 1)

• world - world of center (default is current location of player issuing command)

• color - outline color (color:RRGGBB format)

• fillcolor - fill color (within the outlines) (fillcolor:RRGGBB format)

• opacity - Opacity of the outline strokes (0.0 = transparent, 1.0 = solid)

• fillopacity - Opacity of the filled color areas (0.0 = transparent, 1.0 = solid)

• weight - Stroke weight of outline (0=minimum, higher=thicker)

To delete a circle marker, use the /dmarker deletecircle id:<circle-id> set:<markerset-id> command.

Existing circles, and their attributes, can be shown using the /dmarker listcircles set:<markerset-id> command.

Poly-line markers are used to place a sequence of connected line segments on the world maps. Each poly-line marker is defined by a sequence of 1 or more X,Y,Z coordinates, along with a label, an optional description popup, and associated line color, weight, and opacity settings.

The appearance of the lines can be controlled by setting the color attribute (#RRGGBB), line weight (0-N), and opacity (0.0-1.0).

To create a poly-line, a list of corners needs to be supplied. Corners can be entered as follows:

• Running /dmarker addcorner to add the player's current position as a corner.

• Running /dmarker addcorner <x> <y> <z> or /dmarker addcorner <x> <y> <z> <world> to add a specific coordinate as a corner.

If needed, the corner list can be reset using the /dmarker clearcorners.

Once all the corners are entered, a poly-line marker can be created using the /dmarker addline <line-label> set:<markerset-id> or /dmarker addline id:<line-id> <line-label> set:<markerset-id> commands. Additional attributes can be set with these commands, or later updated using the /dmarker updateline id:<line-id> set:<markerset-id> or /dmarker updateline <line-label> set:<markerset-id> command. These settings include:

• color - outline color (color:RRGGBB format)

• opacity - Opacity of the outline strokes (0.0 = transparent, 1.0 = solid)

• weight - Stroke weight of outline (0=minimum, higher=thicker)

Note: The corners in an existing poly-line cannot currently be updated - delete the existing poly-line and add a new poly-line to update these. Also, the corner list is reset after they are used to create a new poly-line using the /dmarker addline command.

To delete an existing poly-line, use the /dmarker deleteline id:<line-id> set:<markerset-id> command.

Existing lines, and their attributes, can be shown using the /dmarker listlines set:<markerset-id> command.