Model

Models are three-dimensional shapes used in Minecraft that are used to display objects encountered in the game.

The models pertaining to the vast majority of blocks and items can be configured, as well as those of a small selection of entities. Models are stored as JSON files in a resource pack in the assets/<namespace>/models folder.

Block models

• [NBT Compound / JSON Object] The root tag
  • [String] parent: Loads a different model from the given path, in form of a resource location. If both "parent" and "elements" are set, the "elements" tag overrides the "elements" tag from the previous model.
    • Can be set to "builtin/generated" to use a model that is created out of the specified icon. Only the first layer is supported, and rotation can be achieved only by using block states files.
  • [Boolean] ambientocclusion: Whether to use ambient occlusion (true - default), or not (false).
  • [NBT Compound / JSON Object] display: Holds the different places where item models are displayed.
    • [NBT Compound / JSON Object] Position: Named thirdperson_righthand, thirdperson_lefthand, firstperson_righthand, firstperson_lefthand, gui, head, ground, or fixed. 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. Translations are applied to the model before rotations.
      • [NBT List / JSON Array] rotation: Specifies the rotation of the model according to the scheme [x, y, z].
      • [NBT List / JSON Array] translation: Specifies the position of the model according to the scheme [x, y, z]. The values are clamped between -80 and 80.
      • [NBT List / JSON Array] scale: Specifies the scale of the model according to the scheme [x, y, z]. If the value is greater than 4, it is displayed as 4.
  • [NBT Compound / JSON Object] textures: Holds the textures of the model, in form of a resource location or can be another texture variable.
    • [String] particle: What texture to load particles from. This texture is also used as an overlay if you are in a nether portal, and used for water and lava's still textures. This texture is also considered a texture variable that can be referenced as "#particle". Note: All breaking particles from non-model blocks are hard-coded, such as for barriers.
    • [String] Texture variable: Defines a texture variable and assigns a texture.
  • [NBT List / JSON Array] elements: Contains all the elements of the model. They can have only cubic forms. If both "parent" and "elements" are set, the "elements" tag overrides the "elements" tag from the previous model.
    • [NBT Compound / JSON Object] An element.
      • [NBT List / JSON Array] from: Start point of a cuboid according to the scheme [x, y, z]. Values must be between -16 and 32.
      • [NBT List / JSON Array] to: Stop point of a cuboid according to the scheme [x, y, z]. Values must be between -16 and 32.
      • [NBT Compound / JSON Object] rotation: Defines the rotation of an element.
        • [NBT List / JSON Array] origin: Sets the center of the rotation according to the scheme [x, y, z].
        • [String] axis: Specifies the direction of rotation, can be "x", "y" or "z".
        • [Float] angle: Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments.
        • [Boolean] rescale: Specifies whether or not to scale the faces across the whole block by scaling the non-rotated faces by 1 + 1 / (cos(angle) - 1). Can be true or false. Defaults to false.
      • [Boolean] shade: Defines if shadows are rendered (true - default), or not (false).
      • [Int] light_emission: Defines the minimum light level that the element can receive. Can be 0-15, defaults to 0.
      • [NBT Compound / JSON Object] faces: Holds all the faces of the cuboid. If a face is left out, it does not render.
        • [NBT Compound / JSON Object] Face: Named down, up, north, south, west or east. Contains the properties of the specified face.
          • [NBT List / JSON Array] uv: Defines the area of the texture to use according to the scheme [x1, y1, x2, y2]. The texture behavior is inconsistent if UV extends below 0 or above 16. If the numbers of x1 and x2 are swapped (e.g. from 0, 0, 16, 16 to 16, 0, 0, 16), the texture flips. UV is optional, and if not supplied it automatically generates based on the element's position.
          • [String] texture: Specifies the texture in form of the texture variable prepended with a #.
          • [String] 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. It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
          • [Int] rotation: Rotates the texture clockwise 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 uv).
          • [Int] tintindex: Determines whether to tint the texture using a hardcoded tint index. The default value, -1, indicates not to use the tint. Any other number is provided to BlockColors to get the tint value corresponding to that index. However, most blocks do not have a tint value defined (in which case white is used). Furthermore, no vanilla block currently uses multiple tint values, and thus the tint index value is ignored (as long as it is set to something other than -1); it could be used for modded blocks that need multiple distinct tint values in the same block though.

Item models

• [NBT Compound / JSON Object]: The root tag
  • [String] parent: Loads a different model from the given path, in form of a resource location. If both "parent" and "elements" are set, the "elements" tag overrides the "elements" tag from the previous model.
    • Can be set to "item/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 cannot specify the entity, this does not work for all items (only for chests, ender chests, mob heads, shields, banners and tridents).
  • [NBT Compound / JSON Object] display: Holds the different places where item models are displayed.
    • [NBT Compound / JSON Object] Position: Named thirdperson_righthand, thirdperson_lefthand, firstperson_righthand, firstperson_lefthand, gui, head, ground, or fixed. 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. Translations are applied to the model before rotations. If this is specified but not all of translation, rotation and scale are in it, the others aren't inherited from the parent.
      • [NBT List / JSON Array] rotation: Specifies the rotation of the model according to the scheme [x, y, z].
      • [NBT List / JSON Array] translation: Specifies the position of the model according to the scheme [x, y, z]. If the value is greater than 80, it is displayed as 80. If the value is less than -80, it is displayed as -80.
      • [NBT List / JSON Array] scale: Specifies the scale of the model according to the scheme [x, y, z]. If the value is greater than 4, it is displayed as 4.
  • [NBT Compound / JSON Object] textures: Holds the textures of the model, in form of a resource location or can be another texture variable.
    • [String] layerN: Used only 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. Works only in combination with "item/generated".
    • [String] particle: 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 items/barrier.png as blockbreaking particle), which otherwise uses "layer0".
    • [String] Texture variable: Defines a texture variable and assigns a texture.
  • [String] gui_light: Can be "front" or "side". If set to "side", the model is rendered like a block. If set to "front", model is shaded like a flat item. Defaults to "side".
  • [NBT List / JSON Array] elements: Contains all the elements of the model. They can have only cubic forms. If both "parent" and "elements" are set, the "elements" list overrides the "elements" list from the parent model.
    • [NBT Compound / JSON Object] An element.
      • [NBT List / JSON Array] from: Start point of a cuboid according to the scheme [x, y, z]. Values must be between -16 and 32.
      • [NBT List / JSON Array] to: Stop point of a cuboid according to the scheme [x, y, z]. Values must be between -16 and 32.
      • [NBT Compound / JSON Object] rotation: Defines the rotation of an element.
        • [NBT List / JSON Array] origin: Sets the center of the rotation according to the scheme [x, y, z].
        • [String] axis: Specifies the direction of rotation, can be "x", "y" or "z".
        • [Float] angle: Specifies the angle of rotation. Can be 45 through -45 degrees in 22.5 degree increments.
        • [Boolean] rescale: Specifies whether or not to scale the faces across the whole block. Can be true or false. Defaults to false.
      • [Boolean] shade: Defines if shadows are rendered (true - default) or not (false).
      • [Int] light_emission: Defines the minimum light level that the element can receive. Can be 0-15, defaults to 0.
      • [NBT Compound / JSON Object] faces: Holds all the faces of the cuboid. If a face is left out, it does not render.
        • [NBT Compound / JSON Object] Face: Named down, up, north, south, west or east. Contains the properties of the specified face.
          • [NBT List / JSON Array] uv: Defines the area of the texture to use according to the scheme [x1, y1, x2, y2]. If unset, it defaults to values equal to xyz position of the element. The texture behavior is inconsistent if UV extends below 0 or above 16. If the numbers of x1 and x2 are swapped (e.g. from 0, 0, 16, 16 to 16, 0, 0, 16), the texture flips. UV is optional, and if not supplied it automatically generates based on the element's position.
          • [String] texture: Specifies the texture in form of the texture variable prepended with a #.
          • [String] 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. It also determines the side of the block to use the light level from for lighting the face, and if unset, defaults to the side.
          • [Int] rotation: 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 uv).
          • [Int] tintindex: Tints the texture on that face using a tint value referenced from the Items model definition. If no tint color (or the color white) is provided, the texture isn't tinted.
  • [NBT List / JSON Array] overrides: As of 24w45a/ 1.21.4+, overrides have been removed & replaced with a new system. Documentation for it can be found here.

Uses of models

Non-hardcoded models are used in-game in the following contexts:

Use case	Uses	Image	Respects shade=false?
Blocks
Placed blocks	All blocks excluding those listed here		Yes
Falling blocks	All blocks excluding those listed here		Yes
Piston-moved blocks	All blocks excluding those listed here		Yes
Lit TNT	TNT		No
Items
Items in the inventory	All items excluding air		No
Items in the player's hand (first person)	All items excluding air		No
Items in the player's hand (third person) Items held by other players Items held by mobs	All items excluding air		No
Items on the ground	All items excluding air		No
Items in item frames	All items excluding air		No
Totem of undying animation	Any item with the "death protection" component		No

Each of the item display types are used in the following situations:

Use case	Display type
Inventory items	gui
Items equipped on the heads of certain mobs​	head
Dropped items Items held by dolphins Items held by pandas Items held by foxes Thrown projectiles​	ground
Items in item frames	fixed
Items held in a humanoid's left hand​	thirdperson_lefthand
Items held in a humanoid's right hand​ Items held in a humanoid's left hand, if thirdperson_lefthand is left unspecified	thirdperson_righthand
Items held in the left hand in first person	firstperson_lefthand
Items held in the right hand in first person Items held in the left hand in first person, if firstperson_lefthand is left unspecified	firstperson_righthand
Items held by allays Items held by villagers and wandering traders Potions held by witches Ominous item spawner Item display entities Items being brushed out of suspicious sand and gravel Totem of undying animation	​

Limitations

Objects that cannot be remodelled

While most blocks and items can have their model changed, there are a multitude of things that cannot.

For example, no entities (with the exception of item frames and glow item frames) can have their model changed in Java Edition with resource packs alone.

Blocks and fluids

Block	Reason
Air Cave Air Void Air Barrier Light Structure Void	The block is hardcoded to be invisible. Despite having empty physical model data, defining such a model does not change it.
Beds Shulker Boxes Signs Wall Signs Hanging Sign Wall Hanging Sign Heads Wall Heads Chest Trapped Chest Ender Chest Conduit Decorated Pot	The block renders as an entity would. As of 1.21.1, all entity models besides item frames and glow item frames remain hardcoded.
Banners Wall Banners	In addition to using an entity model, these blocks use a layering system to define textures.
Moving Piston	This is a highly technical block which is only used in specific circumstances, with its own special rendering method.
End Gateway End Portal	These blocks utilize a "starfield" effect which is incompatible with the functionality of models.
Bubble Column Lava Water	Fluid rendering is hardcoded and their handling differs significantly from blocks.

Even these blocks (with the exception of the three air variants) have particle textures defined in dedicated model files, however it still stands that actual visual models cannot be changed.

Sub-elements of blocks, such as passively emitted particles and the book on top of the enchanting table, cannot be modified, even though the base block can.

History

[hide]Java Edition pre-Classic
Cave game tech test							Blocks exist, however their models are completely hardcoded, and as such cannot be configured outside of modding.
[hide]Java Edition
1.8			14w06a				Added custom block models.
			14w07a				The model format has now been rewritten. Instead of having just "planes", it now has "planes" and "cubes".
							The rotation of objects are now limited to one directional rotation per object in increments of 22.5 degrees.
			14w11a				Lighting on solid block no longer makes inner sections completely black.
			14w11b				Generic blocks now load models instead of pre-defined shapes.
			April 12, 2014				TheMogMiner posts about upcoming changes to the model format.
			14w17a				Converted most of the remaining static blocks to the model format.
							Added "rotateVariantTextures" to preserve uv details through rotation.
			14w25a				The directional attribute from the uv definition has now been removed and replaced it with explicit texture references. "textureFacing" has been replaced with "texture" parameter, which is now prepended with the hash symbol (#).
							"useAmbientOcclusion" has now been renamed to "ambientocclusion".
							"rotateVariantTextures" has now been renamed to "UV lock".
							"cull" has now been renamed to "cullface", specifies the opposite of which neighboring face causes culling to occur.
							Rotation has now been made more verbose, it is now more clear that it can occur only on a single axis. Example, the rotation for one of the two faces of the "cross" model is now: "rotation": { "origin": [ 8, 8, 8 ], "axis": "y", "angle": 45, "rescale": true },.
							The folder models/blocks/meshes has now been removed and model files are now stored in models/block.
							The folder blockstates has now been added and stores the model selection files previously found in models/block.
							The model format now supports custom item models.
			14w27a				Block state names have now been replaced with data that better reflects the internal data. This does not yet reflect all data for some blocks and switches to using the actual stored data in a future version when numerical data values are completely dropped in favor of block states.
			14w27b				The block state files now support an array of models allowing for random models.
			14w30a				Added the item model "builtin/entity".
1.8.2			pre5				The tag "translation" is now limited to the range of -24 to 24.
							The tag "scale" is now limited to 4 or less.
1.9			15w31a				UV is now optional, and if not supplied it automatically generates based on the element's position.
							Added different models/textures for different damage values, item states, and whether the player is left handed. This works on compasses, clocks, and anything that can have a durability bar. It also contains additional tags for bows and fishing rods.
							Models can now be put together based on block state attributes, such as fences. As a result, the vanilla set of block models was reduced by almost 300 models.
							Block model JSON is now strict, comments and quoteless identifiers are now not allowed.
							"display" tag defaults have now been changed, and the "thirdperson" and "firstperson" tags have now been replaced with "thirdperson_righthand", "thirdperson_lefthand", "firstperson_righthand", and "firstperson_lefthand".
							"parent" and "elements" tags can now coexist, though the top level elements tag overwrites all former ones.
							The option to disable alternate block models has now been removed.
							Multipart tag functionality added.
							Default model offset/position and scale has changed.
							Known bug in this version caused many/all items to be shifted down/positioned wrongly compared to prior versions. MC-82928
			15w31c				Item positions have been fixed to match how they were prior to 15w31a. Although the fishing rod is still different and still is to this day.
1.14			18w43a				Added the item model property "custom_model_data".
1.15.2			Pre-Release 1				The gui_light parameter for item models has been added.
1.21.2			24w33a				The "light_emission" field for models has been added.
			24w36a				All item models can now use the broken property in model overrides that was previously limited to just elytra.
							The model of a item are selected based on the minecraft:item_model component, folowing the format /assets/<namespace>/models/item/<id>.
1.21.4			24w45a				New format has been introduced for describing item models. See Items model definition.
							The minecraft:item_model component now reference a Items model definition.
							overrides section has been removed from existing block models.
							There are no longer any hardcoded paths in models directory - models will be now only used if referenced by definitions in items or blockstates directories.
							Models in models/item that only redirect to a block model have been removed.