Defining custom shaders - webbukkit/dynmap GitHub Wiki

Custom shader definitions can be made by modifying the standard shader definitions, found in shaders.txt, or by adding new or updated definitions to the custom-shaders.txt file (the preferred method).

There are currently three basic classes of shaders, any of which can be used to define a custom shader:

  • org.dynmap.hdmap.DefaultHDShader - this shader supports the equivalents of the FlatMap and KzedMap color models, including the use of colorschemes, and various biome-based coloring

  • org.dynmap.hdmap.CaveHDShader - this shader supports the cave-based coloring scheme

  • org.dynmap.hdmap.TexturePackHDShader - this shader allows the use of Minecraft Texture Packs, including the default texture pack for the Minecraft client

  • org.dynmap.hdmap.TopoHDShader - this shader colors the map to present a topographical map view, based on altitude of the blocks rendered.

  • org.dynmap.hdmap.ChunkStatusHDShader - this is a diagnostic shader, that can be used to produce a map of the 'Status' of the various chunks in a world - see Chunk Status Colors for mapping of status values to colors.

  • org.dynmap.hdmap.ChunkVersionHDShader - this is a diagnostic shader, that can be used to produce a map of the 'DataVersion' of the various chunks in a world, which are mapped to colors based on the Minecraft version of the current encoding of a given chunk (worlds created using older versions of Minecraft are often not upgraded automatically until they are loaded by player activity after a server is upgraded) - see Chunk Version Colors for mapping of status values to colors.

Defining a custom DefaultHDShader shader

The DefaultHDShader class supports the following configuration settings:

shaders:
  - class: org.dynmap.hdmap.DefaultHDShader
    name: myshadername
    colorscheme: ovocean

As with other definitions, the name attribute is required and must be unique. If a custom shader definition provided in the custom-shaders.txt file has the same name as a standard shader, the standard shader will be replaced.

The additional attributes are all optional, with corresponding default behaviors:

  • colorscheme : this defines which colorscheme is used for coloring data. These correspond to the files found in the colorschemes/ directory, and include default, ovocean, flames, and sk89q. These files define coloring data for both normal block coloring, or the various biome-based coloring options. The default value is default.

  • biomecolored : this defines what biome-data based coloring is done, if any. The defined values include none (the default, which results in blocks being colored based on their block type), biome (which colors the blocks based on their biome type), temperature (which colors the blocks based on the raw biome temperature data), or rainfall (which colors the blocks based on the raw biome rainfall/humidity data).

  • transparency : this controls whether transparency information is used or ignored. Defined values are true (the default, where transparency is processed normally) or false (where all blocks are treated as opaque).

Defining a custom CaveHDShader shader

The CaveHDShader currently supports no options beyond the name of the shader, so defining a custom CaveHDShader currently serves no useful purpose. Future Dynmap releases expect to add options for defining the colors used for cave shading.

Defining a custom TexturePackHDShader shader

The TexturePackHDShader class is the most likely shader to be customized, as this is required in order to make use of an add-on Minecraft Texture pack. The TexturePackHDShader class supports the standard texture pack features, as well as many of the add-on features provided through the MCPatcher client patcher, including hi-resolution textures, custom water and lava, and custom biome shading for grass and leaves.

An example of a typical texture pack shader configuration is shown below:

shaders:
  - class: org.dynmap.hdmap.TexturePackHDShader
    name: mytexturepackshader
    texturepack: my-favorite-texturepack-v2.1.zip
    biomeshaded: true
    better-grass: false
    grid-scale: 0

The settings for the TexturePackHDShader include:

  • name : the unique name of the shader

  • texturepack : The name of the texture pack file (if it is a ZIP file), or the directory containing the extracted texture pack (which must include the minimum texture pack files - terrain.png, misc/grasscolor.png, misc/foliagecolor.png, and misc/water.png). Texture pack ZIP files or directories must be in the texturepacks directory under plugins/dynmap.

  • biomeshaded : This setting controls whether grass and leaves are colored based on raw biome data (temperature and rainfall). If set to true (the default), biome-shading is enabled. If set to false, all grass and leaves are shaded consistently, based on the averaged colors from the misc/grasscolor.png and **misc/foliagecolor.png#**files, respectively.

  • better-grass : This setting controls the option to render the sides of grass and snow blocks as done by the BetterGrass client mod. If not defined, the value for better-grass set in configuration.txt applies (which defaults to false).

  • grid-scale : This setting, if defined and greater that zero, will result in a grid being drawn on the map tiles, with a white row and column of blocks every N tiles (so grid-scale: 16 would result in a grid with whitened blocks on every chunk border). Since the block color is changed, the grid will conform to the contour of the map.

An example of a typical topological shader configuration is shown below:

shaders:
  - class: org.dynmap.hdmap.TopoHDShader
    name: topo
    color127: "#FFFFFF"
    color111: "#8B4513"
    color95: "#D2B48C"
    color79: "#FFFF00"
    color63: "#008000"
    color47: "#228B22"
    color31: "#104010"
    color15: "#6B8E23"
    color0: "#696969"
    linecolor: "#000000"
    watercolor: "#0000FF"
    hiddenids: [ 0 ]

The settings for the TopoHDShader include:

  • name : the unique name of the shader

  • linecolor : The #RRGGBB color of the line used to draw the border of areas with common altitides (Y coordinate). If not defined, no border outline is drawn.

  • watercolor : The #RRGGBB color to be used for any water blocks. If defined, this color overrides the color that would otherwise be shown for blocks at the altitude (Y coordinate). If not defined, water is rendered in the same way as any other block.

  • colorN : For N is from 0 to 255, and corresponds to the Y coordinate. Each value provided is an #RRGGBB color to be used for blocks with an altitude of N (Y=N). By default, color0 is #000000 and color255 is #FFFFFF. Any values not provided will be interpolated based on the two nearest values that are defined.

  • hiddennames : Optional parameter, providing a list of block namess to be hidden during generation of the topological map. Default value is just air - [ air ]. Values should be in array format. e.g. [ air, oak_plank, cobblestone, diamond_ore ].