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/<modname>/textures/blocks (where the <modname> 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: <column-base-zero> + <xcount>*<row-base-zero> : 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/<modname>/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 <modname> in 'mods//textures/blocks'). If not specified, the <modname> 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 ":<texture-id>" suffix: the 'txtid=' attribute. By specifying the 'txtid=<texture-id>' attribute, a reference to '<index>' becomes equivalent to '<index>:<texture-id>'. 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 <index> 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 Block Texture Mappings

• To define a simple, solid cube block, see Defining a Simple Block
• To define a cuboid block, see Defining a Cuboid Block
• To define a block based on a custom block renderer, see Defining a Block using a Custom Block Renderer
• To define a block based on a volumetric block model, see Defining a Block using a Volumetric Block Model