Upstream/dynmap
1
0
Fork 0
mirror of https://github.com/webbukkit/dynmap.git synced 2024-11-22 10:15:26 +01:00
Code Issues Projects Releases Wiki Activity

Updated Model Definition Files (markdown)

mikeprimm 2013-11-26 07:40:36 -08:00
parent c0b94ff999
commit 5b96de199d
1 changed files with 10 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Model-Definition-Files.md

@ -1,45 +1,14 @@
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 model definition file for a mod provides the physical shape of custom blocks, when those physical shapes are something other than a simple solid cube. Consequently, if the custom blocks for a mod only consist of simple solid cubes, a model definition file may not be needed for the mod.
The files are line oriented, and can include comment lines (that start with '#'). Each block definition starts with line formatted as follows:
In all cases, the models defined in the model definition file provide a set of surfaces, or patches, that textures defined in the [[Texture Definition Files]] are rendered upon. Since the textures are defined separately from the models, models for blocks with common shapes can easily be reused (e.g. the model for a stair block can be the same for any type of stair block, as the differences in how these stairs are rendered are only which textures are applied to the model for each different block).
block:id=N,data=D,scale=X
There are a variety of methods for defining models, ranging from very simple to quite complex (up to and including custom rendering code provided by add-on Java classes). As always, the simpler methods also tend to be the more efficient.
Where:
## Common lines with Texture Definition Files
In general, the 'modname:', 'version:', 'cfgfile:', 'var:' and other module configuration related lines should be consistent between the Model Definition File and its corresponding Texture Definition File. See [[Common Features for Texture and Model Definition Files]] for details on these commonly defined lines. Inconsistencies here can lead to problems with rendering (due to textures being applied without a corresponding model) or loading errors (due to models being used without required textures being supplied).
* _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.
## Defining Models
To define a simple cuboid model - a rectangular prism where one or more of the dimensions is less than the size of a full block - see [[Defining Cuboid Models]].
To use existing special models - stairs, fences/walls, glass panes/iron fences - see [[Using Custom Block Models]].
To define a volumetric model - a shape represented as a 3D grid of smaller cubes - see [[Defining Volumetric Models]].
To define patch based models - a collection of arbitrary surfaces to have textures applied - see [[Defining Patch Models]].