Upstream
/
dynmap
mirror of https://github.com/webbukkit/dynmap.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated Advanced Block Definitions (markdown)

mikeprimm 2013-11-25 16:41:09 -08:00
parent e1b18c9451
commit d8d4949ce5
2 changed files with 12 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

133
Advanced-Block-Definitions.md

@ -1,133 +0,0 @@
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.
## Textures and Models
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.
## models.txt and custom-models.txt
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/DynmapCore/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. By default the _renderdata_ directory does not exist, and must be created under the _plugins/dynmap_ 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. Note: for certain, special case block types, an additional data value (called the _render data_) is generated and used in preference to the normal _data_ value. Currently, the special case blocks are those where the block ID and data are insufficient to select the model - chests, redstone wire, and fences.
* _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.
## texture.txt and custom-texture.txt
When texture packs are being used to color the blocks found in the map, it is necessary to describe the mapping of graphical data from the resources within the texture pack to the corresponding surfaces or faces of the blocks. This mapping is done by the _texture mappings_ found in the _texture.txt_ internal resource file (this file can be found in the source code at https://github.com/webbukkit/DynmapCore/blob/master/src/main/resources/texture.txt). Additional or custom texture mappings can be defined in the _custom-texture.txt_ file, which can be found in the _renderdata_ directory. By default the _renderdata_ directory does not exist, and must be created under the _plugins/dynmap_ directory. The format of both files is the same.
As with the _models.txt_ file, the texture files can include comments, marked by a '#' character. Each mapping is defined by a single line, formatted as follows:
block:id=V,data=D,_faceid_=_textureval_,_faceid_=_textureval_,....
Where:
* _id_ is the block ID associated with the texture mapping. There must be at least one _id=V_ value provided.
* _data_ is the block data value associated with the texture mapping. If no _data=D_ value is provided, _data=*_ is assumed (all data values). More than one _data_ value can be provided.
* _faceid_ defines the mapping of one or more faces of the block to a specific resource in the texture map, sometimes with a modifier. The valid values for the _faceid_ include:
+ _top_ - the top face of the block
+ _bottom_ - the bottom face of the block
+ _north_ - the north face of the block
+ _south_ - the south face of the block
+ _east_ - the east face of the block
+ _west_ - the west face of the block
+ _allsides_ - all sides of the block (north, south, east, west)
+ _allfaces_ - all faces of the block (all sides, plus top and bottom)
* _textureval_ defines the resource used for the face. Defined values include:
+ 0 to 255 : The index of the patch within terrain.png, with 0 being the first texture on the first row, 16 being the first on the second row, etc.
+ -1 : clear or transparent (no texture)
+ 257 : the texture for stationary water (either from custom_water_still.png, or misc/water.png)
+ 258 : the texture for flowing water (either from custom_water_flowing.png, or misc/water.png)
+ 259 : the texture for stationary lava (either from custom_lava_still.png, or from terrain.png)
+ 260 : the texture for flowing lava (either from custom_lava_flowing.png, or from terrain.png)
+ 261 : the texture for the side of a piston extension (built from the piston block side texture)
+ 262 : the texture for the side of a piston that is extended (build from piston block side)
* _textureval_ can also have a modifier function applied by adding one of the following values to the value encoded:
+ 1000 : the texture should be tinted using the biome-based coloring from misc/grasscolor.png
+ 2000 : the texture should be tinted using the biome-based coloring from misc/foliagecolor.png
+ 4000 : the texture should be rotate 90 degrees clockwise
+ 5000 : the texture should be rotated 180 degrees clockwise
+ 6000 : the texture should be rotated 270 degrees clockwise (90 degrees counter-clockwise)
+ 7000 : the texture should be flipped horizontally (mirror image around vertical axis)
+ 8000 : the texture should be shifted downward by 50% of its height
+ 9000 : the texture should be shifted downward by 50% of its height, and flipped horizontally
+ 10000 : the texture should be transformed to be used on an inclined torch (special case)
+ 11000 : the texture is a grass block side (special case for biome tinting and coloring due to snow)
+ 12000 : the texture is transparent when it represents an interior surface next to another block of the same type (interior of glass or water, for example)
For the special case blocks that have _render data_ generated, an additional attribute can be defined:
* _userenderdata_ : if defined and set to _true_, the generated _render data_ value for the block is used for selecting the matching textures, instead of the block data value. At present, this is only applicable to the redstone wire, chest, and fence blocks (and is only used by the first two).

12
Custom-Block-Definitions.md Normal file

@ -0,0 +1,12 @@
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.
## How blocks are rendered
The rendering of block in Dynmap is accomplished via a number of distinctive mechanisms, reflecting the needs of the different types of blocks defined by Minecraft and by its mods. In all cases, the rendering of a block consists of two core elements: a **model** defining the shape of the block to be rendered, and a set of **textures** used to apply color to the various surfaces of that shape. Thanks to the very 'blocky' nature of Minecraft, the majority of blocks are shaped like simple cubes: consequently, most blocks do not need a custom **model**, and can instead be assumed to be a simple solid cube.
Support files for custom blocks defined by add-on mods are provided through the definition of two files for each mod: one defining the texture mapping (following the naming convention '*-texture.txt', and placed in the 'renderdata' directory (or in a subdirectory under that directory)), and a second defining the models for blocks that are not simple cubes (following the naming convention '*-models.txt', and also placed in the 'renderdata' directory, or a subdirectory). For mods that have nothing but simple cubes, no *-models.txt file is required (as the model for any block without a model defined is assumed to be a simple cube).
## Creating Texture and Model Definition Files
For features common to both texture and model definitions files, see [[Common Features for Texture and Model Definition Files]]
For details on the format of texture definition files, see [[Texture Definition Files]]
For details on the format of model definition files, see [[Model Definition Files]]