-
Notifications
You must be signed in to change notification settings - Fork 0
Advanced Block Definitions
Dynmap supports a data-driven method for defining support for new Minecraft Blocks, which may be used to support customized block types, such as those provided via certain plugins and client modifications. These definitions are VERY sensitive to the internal implementation of the Dynmap ray tracer, and may change or become obsolete on future releases with little or no notice - when practical, this will be avoided, but do understand this before investing too heavily in this.
The rendering of blocks in Dynmap is primarily done by tracing rays into the map, until a block's surface is intersected by the ray. Each time a ray intersects a block, Dynmap looks to see if there is a model corresponding to the block ID and data value. If the block is a solid block, no model is used. If the block is some other shape, the model is used to further trace the ray within the block - either resulting in an intersection with the model or the ray continuing through to the next block on its path. This process is driven by the HD perspective, and is common for all HD maps.
When a ray is found to have intersected with a block (or with the model representing the block), the coloring of the surface is based on the HD shader associated with the map. If the shader is based on using Minecraft textures, the coloring of the intersecting ray is based on a mapping of the data from the texture pack associated with the shader, as described by a texture mapping. The texture mapping describes which part of the images included in the texture pack to use, and any processing or transforms needed to determine the appearance of those images.
The way models are currently provided for the HD perspective module is via the internal resource file, models.txt (which can be found in the source code at https://github.com/webbukkit/dynmap/blob/master/src/main/resources/models.txt). Additional models, or replacements for existing models, can be provided by the custom-models.txt file, which is found in the renderdata directory. Both of these files have the same format.
The files are line oriented, and can include comment lines (that start with '#'). Each block definition starts with line formatted as follows:
block:id=N,data=D,scale=X
Where:
-
id defines the block ID of the block being modeled. There must be at least one id=N attribute, but there may be as many as are needed (different block often share the same shaped model).
-
data defines the value of the block data for the block being modeled. There must be at least one data=D attribute, where D can be '*' (meaning all data values - 0-15) or any value from 0 to 15. There can be as many as are needed.
-
scale defines the scale of the grid of 'sub-blocks' composing the volume of the block. A scale of X implies that the model for the block is being described relative to an X by X by X grid of cells. X must be at least 2.
After the block line, the model can be described in one of two ways: either by describing the layers of cells that compose the block, or by referring to another model and describing a transformation to be applied to that model.
To describe the model directly, the block line is followed by one or more sets of layers. These layers describe the cross-sections of the block, starting from the bottom (layer 0) to the top (layer X-1). Each layer is described by X lines, each containing X characters. The first line of a given layer is the northern edge of the block, while the last line is the southern edge. The first character of each line corresponds to the western edge of the block, and the last represents the eastern edge. Each layer definition is formatted as follows:
layer:A,B,C,D,...
----
-**-
-**-
----
Where:
-
A,B,C,D,... represents the one or more layer numbers described by the definition (this allows a given cross-section to be used more than once in the same model). There must always be at least one layer number, with 0 representing the bottom layer of the model, and (X-1) (for a scale: X model) representing the top.
-
Exactly X lines follow the layer tag, with exactly X characters for each line. These define a grid representing the cells of the layer of the model (X by X), with the first line representing the north edge, the last representing the south edge, the first column representing the west edge, and the last column representing the east edge. If a given character is '*', the cell is considered 'full'. Otherwise, the cell is considered 'empty' (a '-' is used for these characters, by default). The example shown above is representative of a scale: 4 model.
Any layers that are not defined are assumed to be all empty.
Alternately, the model can be defined by referring to another model, and describing a transform (specifically, a rotation about the vertical axis). This is done with the rotate tag, as shown below:
rotate:id=B,data=D,rot=R
Where:
-
id is the ID of the block definition being replicated. This is required, and there can only be one value.
-
data is the block data value of the block definition being replicated. This is required and must be one value.
-
rot defines the degrees of rotation around the vertical axis of the model. 90 causes the new model to be the same as the replicated model after rotating 90 degrees clockwise. 180 represents a 180 degree clockwise rotation. 270 represents a 270 degree clockwise (or 90 degree counter-clockwise) rotation.
Note: the scale of a block defined using the rotate tag MUST match the scale of the block model that is being copied and transformed.