With their introduction in v0.20, the HDMap map type provides a new, more flexible, and (arguably) more complex means of defining and customizing the maps a user can make available on their server. Several details on how HDMaps are defined and structured are intended to offset the additional complexity - but it is important to understand the basic "theory of operations" behind an HDMap definition, in order to know what you need to do to get what you want out of your maps (and not have to work any harder than necessary to get it).

Getting Started Quickly: Enabling the default HD templates

Dynmap includes 3 sets of templates, each providing map definitions for the various types of worlds (normal, nether, and the_end). To select between the three template sets, edit the configuration.txt file, and change the setting of the deftemplatesuffix setting (found near the top of the default configuration.txt file). The currently defined values for this setting include:

• deftemplatesuffix: "" : This causes dynmap to use the 'classic' default templates - these are low resolution and very quick to render, but are far from the most attractive maps. The template files used for this mode are templates/normal.txt, templates/nether.txt, and templates/the_end.txt. This was the default for 0.23 and earlier.

• deftemplatesuffix: vlowres : this selects the "very-low-res" HD maps. These maps are similar to the 'classic' defaults (a surface map, an isometric view from the south-east, and a cave map), but they are rendered using the HD renderer. Also, by default the standard Minecraft texture pack will be used to color the blocks, yielding a much more accurate representation of the map. The template files used for this mode are in templates/normal-vlowres.txt, templates/nether-vlowres.txt, and templates/the_end-vlowres.txt. As of 0.24, these are the default templates.

• deftemplatesuffix: lowres : this selects the "low-res" HD maps. These maps are similar to the 'classic' defaults (a surface map, an isometric view from the south-east, and a cave map), but they are rendered using the HD renderer with about 2-3x the resolution of the "classic" maps. Also, by default the standard Minecraft texture pack will be used to color the blocks, yielding a much more accurate representation of the map. Rendering these maps will take 4-6 times as long as the default 'classic' maps, and about 4x the disk space. The template files used for this mode are in templates/normal-lowres.txt, templates/nether-lowres.txt, and templates/the_end-lowres.txt.

• deftemplatesuffix: hires : this selects the "high-res" HD maps. These maps are the same as the lowres HD maps, except that the surface map (the isometric map) is much higher resolution (4x higher than on lowres, about 8x higher than classic), and rendered from a lower view angle (30 degrees from horizontal versus 60 degrees). The resulting view is VERY nice, but will take quite some time to render (approximately 16x the render time of the lowres map, and about 64x that of the classic map), and much more space (about 16x that of lowres, 64x that of classic). The template files used for this mode are in templates/normal-hires.txt, templates/nether-hires.txt, and templates/the_end-hires.txt.

Once a template set has been selected, the maps can be further customized by editing the template files in use. The following sections describe all the details needed to fully control the map definitions.

The Basics: How to add an HDMap to templates or worlds

Defining an HDMap is, at the high level, the same as it is for the existing map type. As with other maps, an HDMap definition is provided under the maps: section of either a template (in either configuration.txt or one of the files in the templates/ directory) or in a world definition under the worlds: section (in either configuration.txt or the worlds.txt file). The following is a complete example of an HDMap definition:

maps:
  - class: org.dynmap.hdmap.HDMap
    name: myhdmap
    title: "My HD Map"
    prefix: hdm1
    perspective: iso_S_90_lowres
    shader: stdtexture
    lighting: default

As with all maps, an HDMap definition needs 3 basic parameters:

• A class: setting - this identifies the general type of map: for HDMaps, this is org.dynmap.hdmap.HDMap

• A name: setting - this is a unique name for the map (unique among the other maps on a given world). This is used for identifying the map, including when selecting the map using the defaultmap setting, or in the URL parameters.

• A prefix: setting - if not provided, the name setting is used for this. This is used as part of the file and directory names used for the map - so it also needs to be unique among the other prefix values for the other maps on a given world.

Now, the settings specific to HDMaps are used to define three specific aspects of how a map is drawn:

• How do we determine what we see in the scene?

• How do we decide how to color what we see?

• What effect does lighting have on the colors we see?

With HDMaps, the answer to these three questions is determined by the next three settings:

• The perspective: setting provides the name of the perspective definition we use to show the map. The perspective controls the type of projection (currently, only an isometric projection), the direction of view into the map (both angle from North, and angle from horizontal), and the scale of the view (how many pixels per block edge).

• The shader: setting provides the name of the shader definition we use to color the map - how we decide the color of what the -perspective- shows us. This can include shaders that work with specific Minecraft Texture Packs, shaders that use the legacy colorschemes (like those used on the FlatMap and KzedMap definitions), shaders that present biome-based coloring, or shaders for cave rendering.

• The lighting: setting provides the name of the lighting definition we used to modify the colors of the map, based on lighting conditions. This can include rendering shadows, rendering night views, or both night and day views.

To simplify the configuration of these settings, Dynmap comes with a number of predefined perspectives, shaders, and lightings. These definitions can be modified, if needed, or used as examples to allow creation of new definitions specific to a user's needs.

Predefined Perspectives

There are quite a few predefined perspectives, which can be found in perspectives.txt. The names of the predefined settings follow a strict naming pattern, to make it easier to tell which setting to use:

projection _ direction _ angle _ scale

Where:

• projection is the type of viewpoint: currently, only iso (isometric) is supported.

• direction is the direction of view: each of the 8 cardinal directions are supported (N, NE, E, SE, S, SW, W, NW)

• angle is the angle from horizontal of the view: 30 (30 degrees) and 60 (60 degrees) are supported for all cardinal directions, 90 (90 degrees - top-down) is defined for N (from North), S (from South), E (from East) and W (from West) view directions.

• scale is the scale of magnification or detail of the view: vlowres corresponds to 2 pixels per block edge (similar to KzedMap resolution), lowres corresponds to 4 pixels per block edge (about 2x the KzedMap resolution), medres corresponds to 8 pixels per block edge, and hires corresponds to 16 pixels per block edge.

Full List of Predefined Perspectives

Predefined shaders

The predefined shader settings (which are found in shaders.txt) include the following:

• default : the default shader, which uses the standard Minecraft Texture Pack for coloring maps

• defaultscheme : this uses the 'default' colorscheme (as defined in colorschemes/default.txt) for coloring maps

• ovocean : this uses the 'ovocean' colorscheme (as defined in colorschemes/ovocean.txt) for coloring maps

• flames : this uses the 'flames' colorscheme (as defined in colorschemes/flames.txt) for coloring maps

• sk89q : this uses the 'sk89q' colorscheme (as defined in colorschemes/sk89q.txt) for coloring maps

• biome : this uses the biome types for coloring the maps

• temperature : this uses the biome temperature data for coloring the maps

• rainfall : this uses the biome rainfall/humidity data for coloring the maps

• no_transparency : this uses the 'default' colorscheme (as defined in colorschemes/default.txt) for coloring maps, and disables all transparency processing (water, glass, leaves are solid)

• cave : this renders the 'cave view' - showing the boundaries between non-air and air below the ground, color coded from green to blue, based on depth

• stdtexture : this uses the standard Minecraft Texture pack (in texturepack/standard/) to color the maps

• stdtexture-nobiome : this uses the standard Minecraft Texture pack (in texturepack/standard/) to color the maps, but disables biome-based shading of grass and leaves

• topo : this creates a color-coded topographical map, based on altitude : oriented around 128 high generated worlds

• topo256 : this creates a color-coded topographical map, based on altitude : scaled to 256 high worlds

• topo-noplants : this creates a color-coded topographical map, based on altitude : oriented around 128 high generated worlds, with all normal plants and trees hidden

• topo256-noplants : this creates a color-coded topographical map, based on altitude : oriented around 256 high generated worlds, with all normal plants and trees hidden

Predefined lightings

The predefined lighting configuration, which can be found in lightings.txt, include the following:

• default : this is the default: no special processing, no shadows, full daylight

• shadows : this uses full daylight, with shadow and emitted light processing enabled

• night : this uses standard moon-light, with shadow and emitted light processing enabled

• brightnight : this uses an extra bright moon-light (which makes unlit terrain more visible), with shadow and emitted light processing enabled

• nightandday : this causes two sets of tiles to be rendered, one for daytime (corresponding to the shadows settings) and one for night (corresponding to the night settings), which will be automatically presented based on what the time of day is on the corresponding world

• brightnightandday : this is the same as nightandday, except the night tile set is rendered using the same settings as brightnight.

The choice of perspective has a VERY significant impact on both the ultimate size of the map rendered, and the quality of the rendered map. Specifically, the -scale- will radically impact this: as each block on a map will be shown with more pixels, the number of tiles needed to render will go up as the -scale- goes up. lowres maps will involve about 4x as many tiles as a KzedMap (since its about 2x the resolution horizontally and vertically - 2 x 2 = 4). medres is twice the resolution, so another 4x the number of tiles (or 16x from Kzed), hires is twice the resolution again - so 64x the KzedMap tile population! -hires- maps look VERY nice, but be prepared for the initial -fullrender- of the map to take some time (hours to a day or more for larger maps). Low view angles (the 30 degree angle) results in fewer tiles that take a bit more processing to render (a low view angle means more chunks of map needed to render a given tile - as the view cuts more -across- the map than a more vertical view does). Other settings - -shader- and -lighting- have little to no impact on map size, and very small impacts on render time.

Customizing perspectives, shaders, and lightings

For details on defining custom perspectives, shaders or lightings, see the following pages:

Defining Custom Perspectives

Defining Custom Shaders

Defining Custom Lightings

Once a custom perspective, shader or lighting is defined, maps can use them by name, the same as any of the predefined configurations.

Additional HDMap Settings

HDMaps support a number of additional, optional settings, that allow more control of how the map is presented and used by the user. These settings include:

• title : this setting controls the presentation label on the web interface for the map.

• icon : this setting allows control of the URI of the image file used for the map icon on the web interface. If not defined, the value used is images/block_name.png.

• background : this setting provides a color value for the background on the map. Color values are formatted as typical for CSS styles: #rrggbb. If undefined, the background is black (#000000).

• backgroundday : this setting provides a color value for the background of the map during daytime - it overrides the background setting, if defined, when daytime maps are shown. Formatting is CSS style: #rrggbb. Only applicable to night-and-day type maps.

• backgroundnight : this setting provides a color value for the background of the map during nighttime - it overrides the background setting, if defined, when nighttime maps are shown. Formatting is CSS style: #rrggbb. Only applicable to night-and-day type maps.

• mapzoomin : this setting controls the number of zoom-in steps offered for the map beyond the 'native' resolution of the map. These zoom levels stretch the map without showing more map data - the same pixels are shown larger (2x bigger for one step, 4x for two steps, 8x for three steps, etc). By default, the value is 2 (allowing 2 extra zoom ins, corresponding to 2x and 4x).

• image-format : this setting controls the format of the tiles generated for the map. The default is PNG, which is a lossless compression format that maximizes quality, but can yield large files that use significant bandwidth. JPG is a lossy compression option that can trade quality for file size. At very high quality levels, JPG will still tend to be significantly smaller than PNG - 2x is common - with little loss of quality. Lower quality levels can still yield very good map quality and MUCH lower file sizes (6x-10x). The supported values are:

  • png : lossless (but potentially big) PNG (this is the default)

  • jpg : good quality JPG (85% quality) - same as jpg-q85

  • jpg-q75 : fair quality JPG (75% quality)

  • jpg-q80 : fair quality JPG (80% quality)

  • jpg-q85 : good quality JPG (85% quality)

  • jpg-q90 : good quality JPG (90% quality)

  • jpg-q95 : very good quality JPG (95% quality)

  • jpg-q100 : very good quality JPG (100% quality)

Note: As JPEG does not support transparency, the background color for the tiles is rendered into the tiles (particularly for pixels that pass through the scene to the background). If the backgroundday or backgroundnight colors are changed, all tiles will need to be rerendered. Also, if the day and night colors are not the same, a night-and-day enabled lighting option (e.g. the nightandday or brightnightandday lightings) must be used to generate the two tile sets needed (each with the corresponding night and day backgrounds).