HD Map Configuration

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

Default Config

-   class: org.dynmap.hdmap.TexturePackHDShader
    name: default
    texturepack: standard

HD Map Configuration

Getting Started Quickly: Enabling the default HD templates

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

Predefined Perspectives

Predefined shaders

Predefined lightings

Customizing perspectives, shaders, and lightings

Additional HDMap Settings

Contents

Setup

Advanced Configuration

Mod Support

Developers

Clone this wiki locally