Texture Definition Files

Texture definition files (the *-texture.txt files) provide three key sets of data:

• What texture files are needed, and how they need to be loaded
• Which textures are applied to each surface of each custom block, along with any modifiers to how those textures are used (e.g. tinting due to biome-specific shading, rotations, layering, etc).
• In the event that the mod provides custom biomes, additional attributes needed to determine how biome-sensitive textures are rendered can be provided

Defining Texture Files

Over its history, Minecraft has used a number of conventions for defining textures, and has changed these conventions on several occasions (particularly as of 1.5, and again as of 1.6). In order to deal with these differences, a number of definition tokens have been needed.

Defining Textures For 1.6.x and later

As of Minecraft v1.6.0, most built-in textures consist of a single file found under the assets/minecraft/textures/blocks directory (within the Minecraft client JAR file, or within resource pack ZIP files). For v1.6.x or later Minecraft Forge mods, texture resources are generally found within the given mod file (ZIP or JAR) under assets//textures/blocks (where the is the lower-case representation of the mod name). To specify the relative path to use for loading textures, the 'texturepath:' line should be included in the texture file. Once set, the given path will be used for loading any textures specified (or, at least, until the next texturepath: line is processed - at which point, its path will be used for additional textures). For example, the texture path for the mod BiomesOPlenty for Minecraft v1.6.x or later would be:

 texturepath:assets/biomesoplenty/textures/blocks/

Once the path is specified, texture files needed to render the blocks need to be individually specified, using the 'texture:' line. Each such line is formatted as follows:

 texture:id=<texture-id>

Where the is both the identifier that will be used to refer to the texture within the definition file, and is the base part of the file name to be used to load the texture file (by appending the to the texturepath, and then appending the '.png' extension - for example, an ID of 'test123' would load the texture resource assets/biomesoplenty/textures/blocks/tes123.png, given the previous texturepath example). If the ID needs to be different from the filename, the full filename can be specified:

 texture:id=<texture-id>,filename=<full-filename>

For example,

 texture:id=test123.id,filename=assets/biomesoplenty/textures/blocks/tes123.png

For cases where a texture file contains more than one texture, the number of textures horizontally (the xcount) and vertically (the ycount) can be specified:

 texture:id=<texture-id>,xcount=<xcount>,ycount=<ycount>

In this case, the file will be loaded and divided into the grid specified. The individual textures are indexed by a row-ordered index: + * : so, the first texture in the top-left corner of the grid is index 0, the next to the right is 1, etc. until the first one on the next row (which is index xcount)). For single texture files (the default), only the index 0 is used.

Some texture files are specially formatted: with textures defined at locations within the file other than a simple grid (for example, the texture files for chests or for players or mobs). In these cases, see Special Texture File Types for details on the supported types. In these cases, the 'format' attribute is used to define the layout of the file:

 texture:id=<texture-id>,format=<file-format>

Defining Textures For 1.5.x

The textures for Minecraft v1.5.x were handled in a similar way as those of v1.6.x, but with some key differences:

• The vanilla textures were found in the textures/blocks directory within the client JAR (or a texture pack)
• The textures for Minecraft Forge mods were typically found within the mod's ZIP or JAR file in the mods//textures/blocks directory

In the case of v1.5.x mods, the 'texturemod:' line can be used to specify the specific name to be used for the texture path (the value of in 'mods//textures/blocks'). If not specified, the defaults to the name provided in the file's 'modname:' line. So, for v1.5.x style mods, using the line:

 texturemod:<modname>

is the equivalent of using the line

 texturepath:mods/<modname>/textures/blocks/

Otherwise, texture indexing and formats are the same as for v1.6.x and later. Note: use of the 'texturepath:' line results in any further use of the 'texturemod:' line within the definition file being ignored.

Defining Textures for v1.4.x or earlier

Textures in Minecraft v1.4.7 and earlier were almost always in files containing grids of 16 x 16 textures (the equivalent of xcount=16, ycount=16). For these files, the 'texturefile:' line is often used. The 'texturefile:' line is in all ways equivalent to the 'texture:' line, with the exception of defaulting to xcount=16 and ycount=16 (versus the single texture default in 'texture:', equivalent to xcount=1, ycount=1).

Before v1.5.x, there were no consistent conventions used by Minecraft Forge mods for locating of texture resources, so the 'texturepath:' directive, or the filename attribute on the 'texturefile:' or 'texture:' lines, are typically required.

Texture References

Once needed textures have been loaded, a number of different directives can be used to specify the mapping of textures on to the various surfaces of the blocks defined for the mod. In all cases, the references to a specific texture is done through a combination of the index of the texture within the texture file (always 0 for single texture texture-files) and the value of the 'id' attribute specified in the 'texture:' or 'texturefile:' directive. In general, the format is as follows:

 <index>:<texture-id>

On all block definition directives, there is an option to specify a default texture ID to be used for any references that lack the ":" suffix: the 'txtid=' attribute. By specifying the 'txtid=' attribute, a reference to '' becomes equivalent to ':'. Texture index values are limited to values between 0 and 999, inclusively.

Besides selecting the texture to be used, a texture reference can also specify one of a set of modification functions, which will affect how the texture is processed when being rendered. These modification functions are specified by adding one of a set of special values (all multiples of 1000) to the for the texture. The defined values for these modifiers are:

• 1000 : the texture should be tinted using the biome-based coloring for grass (assets/minecraft/textures/colormap/grass.png in v1.6.x and later)

• 2000 : the texture should be tinted using the biome-based coloring for leaves/foliage (assets/minecraft/textures/colormap/foliage.png in v1.6.x and later)

• 3000 : the texture should be tinted using the biome-based coloring for water (via MCPatcher/Optifine - assets/minecraft/mcpatcher/colormap/water.png in v1.6.x and later).

• 4000 : the texture should be rotate 90 degrees clockwise

• 5000 : the texture should be rotate 180 degrees clockwise

• 6000 : the texture should be rotate 270 degrees clockwise

• 7000 : the texture should be flipped horizontally (left to right)

• 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)

• 13000 : the texture is tinted using the color for pine/spruce leaves

• 14000 : the texture is tinted using the color for birch leaves

• 15000 : the texture is tinted using the color for lily pads

• 17000 : the texture is tinted using either the value of the colorMult attribute or by the class specified by the custColorMult attribute (specified separately)

• 18000 : equivalent to 270 degree rotation (6000) and grass toned (1000)

• 19000 : equivalent to 270 degree rotation (6000) and foliage toned (2000)

• 20000 : equivalent to 270 degree rotation (6000) and water toned (3000)

• 21000 : equivalent to multiplier-toned (17000) and clear-inside (12000)

• 22000 : equivalent to foliage toned (2000) and multiplier-toned (17000)

Block ID Numbers

The definition of textures for a specific block requires identifying which block ID is being used by the given block type. While built-in Minecraft standard blocks currently have fixed block ID values, the block IDs for all MinecraftForge mods are controlled through their configuration files. These IDs are loaded via the "cfgfile:" directive (see Common Features for Texture and Model Definition Files for details on this directive, and the mapping of settings from configuration files to usable symbol names). In all block definition directives, the block ID is specified via the 'id=' attribute. The values of the 'id=' attribute can be a number (a constant), a symbol name corresponding to a setting from the mod's configuration file, or a combination of a symbol name, a plus (+), and a number. In all cases, if the value of the ID is zero or negative, the ID value will be ignored (allowing disabled blocks to be easily ignored).

Defining a Simple Block

A simple block is a solid cubic block filling the whole cube where a block is placed. This is the most common kind of block, and is best used whenever possible (for both simplicity of implementation, and for performance). The block texture definition is defined via the 'block:' directive.

A simple block has 6 faces, known by a number of equivalent attributes:

• top or face1 or patch4 (the top of the cube)

• bottom or face0 or patch1 (the bottom of the cube)

• north or face4 or patch0 (the side in the negative X direction - currently west: it was north before Minecraft GA)

• south or face5 or patch3 (the side in the positive X direction - currently east: it was south before Minecraft GA)

• west or face3 or patch5 (the side in the positive Z direction - currently south: it was west before Minecraft GA)

• east or face2 or patch2 (the side in the negative Z direction - currently north: it was east before Minecraft GA)

The texture for each side is set by providing a texture reference for the corresponding attribute, in addition to the required block ID attribute, 'id=':

block:id=<block-id>,<side>=<index-plus-function>:<texture-id>,<side>=<index-plus-function>:<texture-id>,...

There are also convenience attributes for common combinations of faces, allowing the same reference to be applied to multiple sides:

• allfaces (all six faces use the same texture reference)

• allsides (all four faces on the sides of the block - not the top or bottom - use the same texture reference)

• topbottom (the top and bottom faces use the same texture reference)

Due to legacy issues, standard simple blocks also need to have the attribute 'stdrot=true' set. This causes the rotation of the top and bottom textures to be correct - otherwise, those textures will be applied 90 degrees rotated from the in-game equivalent.

If the same texture mapping applies to all metadata values, the 'data=*' attribute should be specified (although this is also the default, when no other 'data=' settings are present). If only specific metadata values should use the given texture mapping, one or more 'data=' settings should also be provided.

If more than one block ID uses the same set of texture mappings, additional 'id=' attributes can be specified on the same "block:" line.

Several other special attributes may be specified, if needed:

• txtid - described above, this allows specifying of a default texture ID to be used by any texture references in the given 'block:' definition that do not have the ':' suffix.

• transparency - this affects how lighting is calculated for the block. If OPAQUE (the default), the block's surfaces are lit based on the light levels of adjacent blocks. If TRANSPARENT, the block's surfaces are lit based on the light levels of the block itself. If SEMITRANSPARENT, the lighting of the block is a special case blend of the two (used by blocks that block light, but do not fill the cube - such as slabs and steps). If LEAVES, the lighting is a special case corresponding to how leaves are handled (generally the same as TRANSPARENT, except on some versions of Spout).

• colorMult - this affects any textures using the multiplier-tinting option (17000, 21000), and consists of a 6 digit hexadecimal value: RRGGBB, where RR is the red component (00-FF), GG is the green component, and BB is the blue component.

• *customColorMult" - this affects any textures using the multiplier-tinting option (17000, 21000), and consists of fully qualified classname of a tinting class. Currently defined values include:

  • org.dynmap.hdmap.colormult.TFBandedWoodColorMultiplier - special tinting function for banded wood in Twilight Forest mod
  • org.dynmap.hdmap.colormult.TFMagicLeafColorMultiplier - special tinting function used for magic tree leaves in Twilight Forest mod
  • org.dynmap.hdmap.colormult.TFSpecialLeafColorMultiplier - special tinting function used for special leaves in Twilight Forest mod

• layer or layer- - this allows textures to be 'stacked' - if any part of the texture on a given side is transparent, the texture from the next layer is applied to those transparent portions. The value of the 'layer' or 'layer-' attribute is the index of the corresponding 'patch' definition to use for the next layer behind the texture for the side matching 'patch' or all patches between 'patch' and 'patch', respectively. For standard simple cubes, the standard sides use patch0 through patch5, so any additional layer textures need to use patch6 or higher.

• patch or *patch-' - these allow definition of additional texture references beyond the first 6 (patch0 through patch5, or the other aliases indicated earlier). For simple cubes, these are only needed for defining layered textures. The value is a texture reference, which is applied to the Mth patch, or to all patches between the Mth and Nth, respectively.