This page describes the basics of models. Forge allows mods to extend the vanilla model format by adding custom model loaders which can have dynamic behavior. These loaders will replace certain but not all elements of the vanilla model format.

Model loaders

Forge allows mods to register custom model loaders, which are specified in JSON using the loader field. These loaders will typically ignore the default elements field in the JSON, and are free to either use or ignore the textures field. However, most model formats defined in Mantle and Tinkers’ Construct reimplement the standard model format making the behavior close to vanilla.

Model loaders generally do not change the behavior of of ambientocclusion,gui_light, display, or overrides from the vanilla model format.

Simple Block Model

Simple block model is a utility in Mantle that allows our custom models to process element data from the parent, along with parse elements from the current model more easily. In other words, it makes the core of the model behave identically to a vanilla model, causing all behavior to just be added on top.

Simple block models provide the following fields in JSON:

  • (Object): The simple block model.
    • parent (Resource Location): If set, will load elements and textures from the given parent if they are not in the current model.
    • elements (Array): List of elements to use. If unset, will load elements from the parent.
      • (Object): An element object.
        • from (Vector): Start of the element in pixels. A full cube would start at [0, 0, 0].
        • to (Vector): End of the element in pixels. A full cube would end at [16, 16, 16].
        • rotation (Object): Rotates the element on the given axis and origin. If unset, does not rotate.
          • origin (Vector): Center of the rotation.
          • axis (String): Specifies the direction of rotation. May be x, y, or z.
          • angle (Number): Rotation angle in degrees, must be -45, -22.5, 0, 22.5, or 45.
          • rescale (Boolean): If true, the model faces will be rescaled after rotation to fit across the full block.
        • shade (Boolean): If true (default), shadows are rendered.
        • faces (Object): Map of face direction to face data.
        • <direction> (Object): A single face. Key is one of six direction values.
          • cullface (direction): If a solid block is placed this direction from the model, this face will not render. If unset, the face never culls.
          • tintindex (Boolean): Color index from the block color getter to fetch to dynamically color the face. If unset, face will not be dynamically tinted.
          • texture (Boolean): Name of a texture from textures to use on this face.
          • uv (Array): Array of UV values in the order [ minU, minV, maxU, maxV ]. Values typically range from 0 to 16, where 0 is the top left corner.
          • forge_data (Forge Face Data, since 1.20): Additional settings for this element from Forge. Overrides the element forge data.
          • emissivity (Integer, until 1.19): Minimum light level for the face between 0 and 15. Defaults to 0.
        • forge_data (Forge Face Data, since 1.20): Additional settings for this element from Forge. Will be overridden by values from the face.

Vector coordinates and UV coordinates are in pixel values (that is, 1/16 of a block).

Forge Face Data

Since 1.20, Forge allows defining custom data on both a model element and an element face. The data has the following format:

  • forge_data (Object, since 1.20): Defines additional data from Forge. If unset, behaves the same way as an empty object.
    • color (ARBG Color): Color to tint the element/face. Defaults to FFFFFFFF (white, that is no tint).
    • block_light (Integer): Minimum block light level for the element/face between 0 and 15. Defaults to 0.
    • sky_light (Integer): Minimum sky light level for the element/face between 0 and 15. Defaults to 0.
    • ambient_occlusion (Boolean): Allows overriding ambientocclusion for a specific block element/face.
    • calcuate_normals (Boolean): If true, manually calculates the normals for this element/face instead of inheriting facing normals like vanilla. Defaults to false.

Colored Block Model

Many model formats from Mantle and Tinkers’ Construct support additional data to change the color of a model face. This is implemented both in utilities made available to other model loaders, and through the mantle:colored_block loader registered by Mantle. Colored block models add the following to the [simple block model] (#simple-block-model) format:

  • (Object): The colored block model.
    • All fields from Simple Block Model.
    • colors (Array): Array of additional data for each element in the block model.
      • (Object): A color data entry. Index of the entry corresponds to an index in elements. If an element has no index in this array it gets the default behavior for all fields.
        • color (ARBG Color): Color to tint the element/face. Defaults to FFFFFFFF (white, that is no tint).
        • luminosity (Integer): Minimum light level for the element between 0 and 15. Defaults to 0.
        • uvlock (ARBG Color): If set, overrides the UV lock setting from the block state JSON for this element.

Note that due to Forge implementing many similar features to this in 1.20, there is a good chance the model loader for colored block models is removed in a later version.