Home

Export format :

Block models

All model and variant files are of the .json format. Block models are used to depict all the blocks in the game, whereas item models are used to display the items in the players hand, on their head (helmets and hats), on the ground and in the inventory. Therefore even the icons used in the inventory are defined in these files.

Variants

There are several different variants of some blocks, hence each block has its own variant file, which lists all his existing variants and links them to their corresponding model. These files are stored in the following folder: assets/minecraft/blockstates. You should not change the names of these files or the variants themselves. They are hardcoded in the game and must be used in resource packs as well.

• The root tag
  • variants: Holds the names of all the variants of the block.
    • A variant: Name of a variant, which consists of the relevant BlockStates separated by commas. A block with just one variant uses normal as a name for its variant. Each variant contains the properties of its model. If more than one model is used, these models must be specified in separate -tags, which are subsidiary to the variant tag.
      • A model: Contains the properties of a model, if more than one model is used for the same variant. All specified models alternate in the game.
        • model: Specifies the path to the model file of the block, starting in assets/minecraft/models/blocks.
        • x: Rotation of the model on the x-axis in increments of 90 degrees.
        • y: Rotation of the model on the y-axis in increments of 90 degrees.
        • uvlock: Rotates the texture with the block, if false (default).
        • weight: Probability of the model being used in the game. The default value is 1 (=100%).
      • model: Specifies the path to the model file of the block, starting in assets/minecraft/models/blocks.
      • x: Rotation of the model on the x-axis in increments of 90 degrees.
      • y: Rotation of the model on the y-axis in increments of 90 degrees.
      • uvlock: Rotates the texture with the block, if false (default).

Example: Torch

The torch has several variants: It can be placed on the ground or at a wall facing in four different directions. This example is taken from the file torch.json, which can be found at assets/minecraft/blockstates.

File: torch.json

{
    "variants": {
        "facing=up": { "model": "normal_torch" },
        "facing=east": { "model": "normal_torch_wall" },
        "facing=south": { "model": "normal_torch_wall", "y": 90 },
        "facing=west": { "model": "normal_torch_wall", "y": 180 },
        "facing=north": { "model": "normal_torch_wall", "y": 270 }
    }
}

"facing=up" is the variant of the torch standing on the ground andlinks to the corresponding model "normal_torch". A torch can be placed on all four sides of a block and therefore needs four different variants, one for each side. These are called "facing=east", "facing=west", "facing=south" and "facing=north". All four variants use "normal_torch_wall" as their model, which is rotated by a multiple of 90 degrees to align with the different sides of the block they are placed on.

Example: Grass Block

The grass block has two variants, whereby the first one holds four different models. This example is taken from the file grass.json, which can be found at assets/minecraft/blockstates.

File: grass.json

{
    "variants": {
        "snowy=false": [
            { "model": "grass_normal" },
            { "model": "grass_normal", "y": 90 },
            { "model": "grass_normal", "y": 180 },
            { "model": "grass_normal", "y": 270 }
        ],
        "snowy=true":  { "model": "grass_snowed" }
    }
}

The non-snow-covered grass block (snowy=false) holds four models, which all use the same block model, but each one is rotated by a multiple of 90 degrees. As there are four models and the count-tag is not used for any of them, each one has a chance of 25% to be used every time a block is placed.

Block models

The folder assets/minecraft/models/block holds the model files for all the specified variants. The names of the files can be changed, but must always correspond with the names used in the variant files.

• The root tag
  • parent: Loads a different model from the given path, starting in assets/minecraft/models .
  • ambientocclusion: Whether to use ambient occlusion (true - default), or not (false).
  • textures: Holds the textures of the model. Each texture starts in assets/minecraft/textures or can be another texture variable.
    • particle: What texture to load particles from.
    • A texture variable: Defines a texture variable and assigns a texture.
  • elements: Contains all the elements of the model. they can only have cubic forms.
    • An element
      • from: Start point of a cube according to the scheme [x, y, z]. Values must be between -16 and 32.
      • to: Stop point of a cube according to the scheme [x, y, z]. Values must be between -16 and 32.
      • rotation: Defines the rotation of an element.
        • origin: Sets the center of the rotation according to the scheme [x, y, z], defaults to [8, 8, 8].
        • axis: Specifies the direction of rotation, can be "x", "y" or "z".
        • angle: Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments. Defaults to 0.
        • rescale: Specifies whether or not to scale the faces across the whole block. Can be true or false. Defaults to false
      • shade: Defines if shadows are rendered (true - default), not (false).
      • faces: Holds all the faces of the cube. If a face is left out, it will not be rendered.
        • down, up, north, south, west or east: Contains the properties of the specified face.
          • uv: Defines the area of the texture to use according to the scheme [x1, y1, x2, y2].
          • texture: Specifies the texture in form of the texture variable prepended with a #.
          • cullface: Specifies whether a face does not need to be rendered when there is a block touching it in the specified position. The position can be: down, up, north, south, west, or east.
          • rotation: Rotates the texture in increments of 90 degrees.
          • tintindex: Determines whether to tint the texture using a hardcoded tint index. The default is not using the tint, and any number causes it to use tint. Note that only certain blocks have a tint index, all others will be unaffected.

Example: Standing Torch

For simplicity, this example only describes the standing torch, which is defined in the files torch.json and normal_torch.json stored in the folder assets/minecraft/models/block.

File: torch.json

{
    "ambientocclusion": false,
    "textures": {
        "particle": "#torch"
    },
    "elements": [
        {   "from": [ 7, 0, 7 ],
            "to": [ 9, 10, 9 ],
            "shade": false,
            "faces": {
                "down": { "uv": [ 7, 13, 9, 15 ], "texture": "#torch" },
                "up":   { "uv": [ 7,  6, 9,  8 ], "texture": "#torch" }
            }
        },
        {   "from": [ 7, 0, 0 ],
            "to": [ 9, 16, 16 ],
            "shade": false,
            "faces": {
                "west": { "uv": [ 0, 0, 16, 16 ], "texture": "#torch" },
                "east": { "uv": [ 0, 0, 16, 16 ], "texture": "#torch" }
            }
        },
        {   "from": [ 0, 0, 7 ],
            "to": [ 16, 16, 9 ],
            "shade": false,
            "faces": {
                "north": { "uv": [ 0, 0, 16, 16 ], "texture": "#torch" },
                "south": { "uv": [ 0, 0, 16, 16 ], "texture": "#torch" }
            }
        }
    ]
}

This file is used to create the model of the torch, which is used for the normal and the redstone torch. Therefore the elements-tag is used to create three elements or cubes. Only two faces of each cube are rendered, as only two faces of each one have been specified. "uv" is used to determine the area where the texture is used. The texture variable "#torch" is used for the particles and the cubes and has not yet been defined.

File: normal_torch.json

{
    "parent": "block/torch",
    "textures": {
        "torch": "blocks/torch_on"
    }
}

This file represents the model of the normal standing torch. It loads the model of previously defined standing torch with the help of "parent" and inherits all the properties of the file torch.json. As this file is only used for the normal torch, the texture can now be specified. The texture"torch_on" is now assigned to the texture variable "torch" (without #) and will therefore be used for the previously loaded model and its particles, as specified in the other file.

Example: Any Block

This example describes the fundamental structure of most normal blocks in Minecraft. All these blocks use the same basic model and only apply their texture to it, as already described in the example above. This model is defined in the file cube.json which can be found in the folder assets/minecraft/models/block.

File: cube.json

{
    "elements": [
        {   "from": [ 0, 0, 0 ],
            "to": [ 16, 16, 16 ],
            "faces": {
                "down":  { "texture": "#down", "cullface": "down" },
                "up":    { "texture": "#up", "cullface": "up" },
                "north": { "texture": "#north", "cullface": "north" },
                "south": { "texture": "#south", "cullface": "south" },
                "west":  { "texture": "#west", "cullface": "west" },
                "east":  { "texture": "#east", "cullface": "east" }
            }
        }
    ]
}

Features, that have already been described above will not be mentioned again. The use of "cullface": "down" prevents the bottom face of the block from being rendered, if there is another adjacent block underneath it. The same applies to all the other faces of the block.

Example: Sapling

This example describes the fundamental structure used by all saplings, without assigning a specific texture. The model is specified in cross.json, the texture would e.g. be assigned in oak_sapling.json. Both files are stored in the folder assets/minecraft/models/block.

File: cross.json

{
    "ambientocclusion": false,
    "textures": {
        "particle": "#cross"
    },
    "elements": [
        {   "from": [ 0.8, 0, 8 ],
            "to": [ 15.2, 16, 8 ],
            "rotation": { "origin": [ 8, 8, 8 ], "axis": "y", "angle": 45, "rescale": true },
            "shade": false,
            "faces": {
                "north": { "uv": [ 0, 0, 16, 16 ], "texture": "#cross" },
                "south": { "uv": [ 0, 0, 16, 16 ], "texture": "#cross" }
            }
        },
        {   "from": [ 8, 0, 0.8 ],
            "to": [ 8, 16, 15.2 ],
            "rotation": { "origin": [ 8, 8, 8 ], "axis": "y", "angle": 45, "rescale": true },
            "shade": false,
            "faces": {
                "west": { "uv": [ 0, 0, 16, 16 ], "texture": "#cross" },
                "east": { "uv": [ 0, 0, 16, 16 ], "texture": "#cross" }
            }
        }
    ]
}

To create the usual shape of the saplings, both elements are being rotated by 45 degrees. Therefor the origin and the axis of rotation are set to the specified values, the angle is set to 45 degrees and "rescale" is set to true. The latter causes the model to be scaled on the axes it has not been rotated on, so that it takes up the same space as it did before rotating it (see comparison images).

"rescale": false	"rescale": true

Item models

As items do not have different variants, there is no need to specify them. The folder assets/minecraft/models/item contains all the model files. The names of the files are hardcoded and should not be changed.

• The root tag
  • parent: Loads a different model from the given path, starting in assets/minecraft/models.
    • Can be set to "builtin/generated" to use a model that is created out of the specified icon.
    • Can be set to "builtin/entity" to load a model from an entity file. As you can not specify the entity, this does not work for all items (only for chests, ender chests, mob heads and banners).
    • Needs to be set to "builtin/compass" or "builtin/clock" for the compass and the clock.
  • textures: Holds the textures of the model. Each texture starts in assets/minecraft/textures or can be another texture variable.
    • layer#: Only used to specify the icon of the item used in the inventory. There can be more than just one layer (e.g. for spawn eggs), but the amount of possible layers is hardcoded for each item. Only works in combination with "builtin/generated".
    • particle: What texture to load particles from.
    • A texture variable: Defines a texture variable and assigns a texture.
  • elements: Contains all the elements of the model. They can only have cubic forms.
    • An element
      • from: Start point of a cube according to the scheme [x, y, z]. Values must be between -16 and 32.
      • to: Stop point of a cube according to the scheme [x, y, z]. Values must be between -16 and 32.
      • rotation: Defines the rotation of an element.
        • origin: Sets the center of the rotation according to the scheme [x, y, z], defaults to [8, 8, 8].
        • axis: Specifies the direction of rotation, can be "x", "y" or "z".
        • angle: Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments. Defaults to 0.
      • faces: Holds all the faces of the cube. If a face is left out, it will not be rendered.
        • down, up, north, south, west or east: Contains the properties of the specified face.
          • uv: Defines the area of the texture to use according to the scheme [x1, y1, x2, y2].
          • textures: Specifies the texture in form of the texture variable prepended with a #.
          • cull: Specifies whether non-visible elements should be rendered (true), or not (false).
          • rotation: Rotates the texture in increments of 90 degrees.
  • display: Holds the different places where item models are displayed.
    • thirdperson, firstperson, gui or head: Place where an item model is displayed. Holds its rotation, translation and scale for the specified situation.
      • rotation: Specifies the rotation of the model according to the scheme [x, y, z].
      • translation: Specifies the translation of the model according to the scheme [x, y, z].
      • scale: Specifies the scale of the model according to the scheme [x, y, z].

Example: Torch

This example describes the torch as an item. The model can be found in the torch.json, which is stored in the folder assets/minecraft/models/item.

File: torch.json

{
    "parent": "builtin/generated",
    "textures": {
        "layer0": "blocks/torch_on"
    }
    "display": {
        "thirdperson": {
            "rotation": [ -90, 0, 0 ],
            "translation": [ 0, 1, -3 ],
            "scale": [ 0.55, 0.55, 0.55 ]
        },
        "firstperson": {
            "rotation": [ 0, -135, 25 ],
            "translation": [ 0, 4, 2 ],
            "scale": [ 1.7, 1.7, 1.7 ]
        }
    }
}

The "parent"-tag uses "builtin/generated", so that game uses the standard model of the torch, which has been generated out of the 2D graphic used for the item icon. The icon is specified with the "layer0"-tag and the texture, that has already been used for the block model, is used for the icon as well. As there is just one layer hard coded for the torch, there cannot be any more layers added. Furthermore, the display properties for the torch are specified, so that it will be displayed correctly in every possible situation. The torch cannot be placed on a players head and uses the specified icon in the inventory, so there is no need to adjust the model for these situations. To line the model up with the players hand in first and third person view, the model needs to be rotated, moved and scaled, which is done for each of the two situation separately.