Model

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, in the inventory, in Item Frames and on Armor Stands. As there are different variants of some blocks, block states are used to link these with the corresponding models. Each model and each block state has its own file, which is of the  format. Even the icons used in the inventory are defined in these files.

Block states
There are several different variants of some blocks (like doors, which can be open or closed), hence each block has its own block state file, which lists all its existing variants and links them to their corresponding model(s). Blocks can also be compound of several different models at the same time, called "multipart". The models are then used depending on the block states of the block. These files are stored in the following folder:. The files are used directly based on their filename, thus a block state file with another name than the existing ones will not affect any block.


 * The root tag
 * Holds the names of all the variants of the block.
 * Name of a variant, which consists of the relevant block states separated by commas. A block with just one variant uses  as a name for its variant. Each variant can have one model or an array of models and contains their properties. If set to an array, the model will randomly be chosen from the options given, with each option being specified in separate subsidiary -tags.
 * Contains the properties of a model, if more than one model is used for the same variant. All specified models alternate in the game.
 * Specifies the path to the model file of the block, starting in.
 * Rotation of the model on the x-axis in increments of 90 degrees.
 * Rotation of the model on the y-axis in increments of 90 degrees.
 * Can be  or   (default). Locks the rotation of the texture of a block, if set to  . This way the texture will not rotate with the block when using the  and -tags above.
 * Sets the probability of the model for being used in the game, defaults to 1 (=100%). If more than one model is used for the same variant, the probability will be calculated by dividing the individual model’s weight by the sum of the weights of all models. (For example, if three models are used with weights 1, 1, and 2, then their combined weight would be 4 (1+1+2). The probability of each model being used would then be determined by dividing each weight by 4: 1/4, 1/4 and 2/4, or 25%, 25% and 50%, respectively.)
 * Specifies the path to the model file of the block, starting in.
 * Rotation of the model on the x-axis in increments of 90 degrees.
 * Rotation of the model on the y-axis in increments of 90 degrees.
 * Can be  or   (default). Locks the rotation of the texture of a block, if set to  . This way the texture will not rotate with the block when using the  and -tags above.
 * Used instead of to combine models based on block state attributes.
 * Determines a case and which model should apply in that case.
 * A list of cases that have to be met for the model to be applied. If unset, the model always applies.
 * Matches if any of the contained cases return true. Cannot be set along side other cases.
 * A list of cases that all have to match the block to return true.
 * A single case that has to match one of the block states. It can be set to a list seperated by  to allow multiple values to match.
 * A single case that has to match one of the block states. It can be set to a list seperated by  to allow multiple values to match. Cannot be set along side the -tag.
 * Determines the model(s) to apply and its properties. There can be one model or an array of models. If set to an array, the model will randomly be chosen from the options given, with each option being specified in separate subsidiary -tags.
 * Contains the properties of a model, if more than one model is used for the same variant. All specified models alternate in the game.
 * Specifies the path to the model file of the block, starting in.
 * Rotation of the model on the x-axis in increments of 90 degrees.
 * Rotation of the model on the y-axis in increments of 90 degrees.
 * Can be  or   (default). Locks the rotation of the texture of a block, if set to  . This way the texture will not rotate with the block when using the  and -tags above.
 * Sets the probability of the model for being used in the game, defaults to 1 (=100%). If more than one model is used for the same variant, the probability will be calculated by dividing the individual model’s weight by the sum of the weights of all models. (For example, if three models are used with weights 1, 1, and 2, then their combined weight would be 4 (1+1+2). The probability of each model being used would then be determined by dividing each weight by 4: 1/4, 1/4 and 2/4, or 25%, 25% and 50%, respectively.)
 * Specifies the path to the model file of the block, starting in.
 * Rotation of the model on the x-axis in increments of 90 degrees.
 * Rotation of the model on the y-axis in increments of 90 degrees.
 * Can be  or   (default). Locks the rotation of the texture of a block, if set to  . This way the texture will not rotate with the block when using the  and -tags above.

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, which can be found at.

{    "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 } } }
 * torch.json

is the variant of the torch standing on the ground and links to the corresponding model. 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,  ,   and. All four variants use  as their model, which is rotated by a multiple of 90 degrees around the   axis 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, which can be found at.

{    "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" } } }
 * grass.json

The non-snow-covered grass block 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 -tag is not used for any of them, each one has a chance of 25% to be used every time a block is placed.

Example: Oak Fence
The oak fence uses the  format. This example is taken from  in.

{   "multipart": [ {  "apply": { "model": "oak_fence_post" }}, {  "when": { "north": "true" }, "apply": { "model": "oak_fence_side", "uvlock": true } },       {   "when": { "east": "true" }, "apply": { "model": "oak_fence_side", "y": 90, "uvlock": true } },       {   "when": { "south": "true" }, "apply": { "model": "oak_fence_side", "y": 180, "uvlock": true } },       {   "when": { "west": "true" }, "apply": { "model": "oak_fence_side", "y": 270, "uvlock": true } }   ] }

While the first model, the fence post, is always used, the other models are only used if certain conditions are met. Here the sides of the fence are only applied, if there is another adjacent block next to this one. As there is just one model for the post and another one for all the sides of the fence, which then is rotated by increments of 90 degrees, the amount of models needed for all the different possible set-ups of fences can be reduced to two. Compared to the five models and 16 variants used in 1.8, this is a rather big improvement.

Example: Redstone Wire
The redstone wire model uses the  format. This example is taken from  in

{   "multipart": [ {  "when": { "OR": [ {"north": "none", "east": "none", "south": "none", "west": "none"}, {"north": "side|up", "east": "side|up" }, {"east": "side|up", "south": "side|up" }, {"south": "side|up", "west": "side|up"}, {"west": "side|up", "north": "side|up"} ]},           "apply": { "model": "redstone_dot" } },       {   "when": { "OR": [ { "north": "side|up" }, { "north": "none", "east": "none", "south": "side|up", "west": "none" } ]},           "apply": { "model": "redstone_side0" } },       {   "when": { "OR": [ { "south": "side|up" }, { "north": "side|up", "east": "none", "south": "none", "west": "none" } ]},           "apply": { "model": "redstone_side_alt0" } },       {   "when": { "OR": [ { "east": "side|up" }, { "north": "none", "east": "none", "south": "none", "west": "side|up" } ]},           "apply": { "model": "redstone_side_alt1", "y": 270 } },       {   "when": { "OR": [ { "west": "side|up" }, { "north": "none", "east": "side|up", "south": "none", "west": "none" } ]},           "apply": { "model": "redstone_side1", "y": 270 } },       {   "when": { "north": "up" }, "apply": { "model": "redstone_up" } },       {   "when": { "east": "up" }, "apply": { "model": "redstone_up", "y": 90 } },       {   "when": { "south": "up" }, "apply": { "model": "redstone_up", "y": 180 } },       {   "when": { "west": "up" }, "apply": { "model": "redstone_up", "y": 270 } }   ] }

This model is dynamically created. With the first condition, it is determining cases where the  model should be added, which requires either all of the four sides being set to "none", or any two sides that form a corner both being set either to   or.

The last case only tests one condition, which asks if  is set to , and if so it applies the model.

Block models
The folder  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
 * Loads a different model from the given path, starting in . If both   and   are set, the   tag overrides the   tag from the previous model.
 * Can be set to  to use a model that is created out of the specified icon. Note that only the first layer is supported, and rotation can only be achieved using block states files.
 * Whether to use ambient occlusion (  - default), or not.
 * Holds the different places where item models are displayed.
 * Place where an item model is displayed. Holds its rotation, translation and scale for the specified situation. fixed refers to item frames, while the rest are as their name states. Note that translations are applied to the model before rotations.
 * Specifies the rotation of the model according to the scheme.
 * Specifies the position of the model according to the scheme . If the value is greater than 80, it is displayed as 80. If the value is less then -80, it is displayed as -80.
 * Specifies the scale of the model according to the scheme . If the value is greater than 4, it is displayed as 4.
 * Holds the textures of the model. Each texture starts in  or can be another texture variable.
 * What texture to load particles from. This texture is used if you are in a nether portal. Note: All breaking particles from non-model blocks are hard-coded.
 * Defines a texture variable and assigns a texture.
 * Contains all the elements of the model. they can only have cubic forms. If both  and   are set, the   tag overrides the   tag from the previous model.
 * Start point of a cube according to the scheme . Values must be between -16 and 32.
 * Stop point of a cube according to the scheme . Values must be between -16 and 32.
 * Defines the rotation of an element.
 * Sets the center of the rotation according to the scheme, defaults to.
 * Specifies the direction of rotation, can be,   or.
 * Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments. Defaults to 0.
 * Specifies whether or not to scale the faces across the whole block. Can be true or false. Defaults to false.
 * Defines if shadows are rendered ( - default), not.
 * Holds all the faces of the cube. If a face is left out, it will not be rendered.
 * Contains the properties of the specified face.
 * Defines the area of the texture to use according to the scheme . If unset, it defaults to values equal to xyz position of the element. The texture behavior will be inconsistent if UV extends below 0 or above 16. If the numbers of   and   are swapped (e.g. from   to  ), the texture will be flipped. UV is optional, and if not supplied it will automatically generate based on the element's position.
 * Specifies the texture in form of the texture variable prepended with a.
 * 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:,  ,  ,  ,  , or  . It will also determine which side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
 * Rotates the texture by the specified number of degrees. Can be 0, 90, 180, or 270. Defaults to 0. Rotation does not affect which part of the texture is used. Instead, it amounts to permutation of the selected texture vertexes (selected implicitly, or explicitly though ).
 * 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.
 * 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  and   stored in the folder.

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  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. is used to determine the area where the texture is used. The texture variable  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  and inherits all the properties of the file. As this file is only used for the normal torch, the texture can now be specified. The texture is now assigned to the texture variable    (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, which can be found in the folder. 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  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, the texture would e.g. be assigned in. Both files are stored in the folder.

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. Therefore the origin and the axis of rotation are set to the specified values, the angle is set to 45 degrees and  is set to. 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).

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


 * The root tag
 * Loads a different model from the given path, starting in . If both   and   are set, the   tag overrides the   tag from the previous model.
 * Can be set to  to use a model that is created out of the specified icon.
 * Can be set to  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, shields and banners).
 * Needs to be set to  or   for the compass and the clock.
 * Holds the textures of the model. Each texture starts in  or can be another texture variable.
 * 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.
 * What texture to load particles from. Used to determine the "crumb" particles generated by food items, as well as to determine the barrier particle (but it always uses  as blockbreaking particle), which otherwise will use "layer0".
 * Defines a texture variable and assigns it a texture.
 * Contains all the elements of the model. They can only have cubic forms. Cannot be set along side.
 * Start point of a cube according to the scheme . Values must be between -16 and 32.
 * Stop point of a cube according to the scheme . Values must be between -16 and 32.
 * Defines the rotation of an element.
 * Sets the center of the rotation according to the scheme, defaults to.
 * Specifies the direction of rotation, can be,   or.
 * Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments. Defaults to 0.
 * Holds all the faces of the cube. If a face is left out, it will not be rendered.
 * Contains the properties of the specified face.
 * Defines the area of the texture to use according to the scheme . If unset, it defaults to values equal to xyz position of the element. The texture behavior will be inconsistent if UV extends below 0 or above 16. If the x or y number are swapped, the texture will be flipped in that direction. UV is optional, and if not supplied it will automatically generate based on the element's position.
 * Specifies the texture in form of the texture variable prepended with a.
 * 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:,  ,  ,  ,  , or  . It will also determine which side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
 * Rotates the texture in increments of 90 degrees.
 * 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 (except for spawn eggs, where 0 causes it to use the first color, and 1 causes it to use the second color). Note that only certain items or certain layers of items (e.g. potions) have a tint index, all others will be unaffected.
 * Holds the different places where item models are displayed.
 * Place where an item model is displayed. Holds its rotation, translation and scale for the specified situation. fixed refers to item frames, while the rest are as their name states.
 * Specifies the rotation of the model according to the scheme.
 * Specifies the position of the model according to the scheme . If the value is greater than 80, it is displayed as 80. If the value is less then -80, it is displayed as -80.
 * Specifies the scale of the model according to the scheme . If the value is greater than 4, it is displayed as 4.
 * Determines cases which a different model should be used based on item tags. All cases are evaluated in order from top to bottom and last predicate that mathches will override. However, overrides are ignored if it has been already overriden once, for example this avoids recursion on overriding to the same model.
 * A single case.
 * Holds the cases.
 * A single case tag. See item tags for a full list of available tags.
 * The path to the model to use if the case is met, starting in
 * The path to the model to use if the case is met, starting in

Item tags
Some items support additional tags for model overrides. Below is a full list of available tags.
 * : Used on compasses to determine the current angle, expressed in a decimal value of less than one.
 * : Used on shields to determine if currently blocking. If , the player is blocking.
 * : Used on Elytra to determine if broken. If , the Elytra is broken.
 * : Used on fishing rods to determine if the fishing rod has been cast. If, the fishing rod has been cast.
 * : Used on ender pearls and chorus fruit to determine the remaining cooldown, expressed in a decimal value between 0 and 1.
 * : Used on items with durability to determine the amount of damage, expressed in a decimal value between 0 and 1.
 * : Used on items with durability to determine if it is damaged. If, the item is damaged. Note that if an item has the unbreakable tag, this may be   while the item has a non-zero   tag.
 * : Determines the model used by left handed players. It will affect the item they see in inventories, along with the item players see them holding or wearing.
 * : Determines the amount a bow has been pulled, expressed in a decimal value of less than one.
 * : Used on bows to determine if the bow is being pulled. If, the bow is currently being pulled.
 * : Used on clocks to determine the current time, expressed in a decimal value of less than one.

Example: Torch
This example describes the torch as an item. The model can be found in the, which is stored in the folder.

File: torch.json

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

The -tag uses , so that the 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 -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 left or right 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.

Example: Fishing Rod
This example describes the fishing rod as of 1.9. The model can be found in the, which is stored in the folder.

{   "parent": "item/handheld_rod", "textures": { "layer0": "items/fishing_rod_uncast" },   "overrides": [ {           "predicate": { "cast": 1 },           "model": "item/fishing_rod_cast" }   ] }

In this model, the normal model is overridden if the fishing rod is cast, causing it to instead display the model

History
Modelldaten Modèles Modele bloków 模型 モデル