Minecraft:Items model definition

Items models<ref>Name from the official name ("Item model", 24w45a news) and file directory (assets/<namespace>/items).</ref>, commonly referred to as Client Items, Item definitions or Itemstates, are processor files used by the game to define and select which Minecraft:model to use for rendering items, depending of various criteria such as components, item interactions, their position in the inventory, or numerous other in-game values.

Items models are stored as Minecraft:JSON files in a Minecraft:resource pack in the Template:Cd folder.

Which items model is used by an item is based on the component Template:DCL, which references the Minecraft:identifier of the items model at Template:Cd, and can be changed through Minecraft:commands.

JSON format

• Template:Nbt Root object
  • Template:Nbt: Optional. Describes if a down-and-up animation should be played in first-person view when the item slot is changed (either type, count, components or by swapping the item into the other hand). Default: Template:Cd.
  • Template:Nbt: Optional. Describes if the items model is allowed to render bigger than the item slot. If Template:Cd the render will be clipped to the item slot size. Default: Template:Cd.
    • The ability of items being rendered outside of their slots is not considered officially supported by Mojang. It's a backward compatibility until an official functionality is developed at some point in the future.<ref>Template:Mcnet</ref>
  • Template:Nbt: Optional. Indicates how fast the item moves up and down when swapping items in hotbar. Large speeds can allow items that take more of the screen space to fully duck before swapped into the next item. Default: Template:Cd.
  • Template:Nbt: Set the basic Items model object.

Items model

• Template:Nbt An Items model object
  • Template:Nbt: One of Template:Cd.
  • Template:Nbt: This field uses the same format as the transformation field of the Minecraft:display entity, i.e. either an array of 16 numbers representing a matrix or structure with decomposed translation, scale and rotation info.
    • For types with children (Template:Cd), the transformation will be composed with the transformation of the children, except for Template:Cd.
    • Model transformations will be applied AFTER item display transformations (i.e. display section in model files).
    • Model transformations is not supported in Template:Cd type.
  • Additional fields depending on value of type, see Template:Slink.

Items model types

model

Render a plain model from the Template:Cd directory.

• Template:Nbt Root model items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Specifies the path to the model file of the item, in form of a Namespaced ID.
  • Template:Nbt: Optional. List of tint sources to apply to the elements of rendered model (first entry applies to Template:Cd 0, second one to Template:Cd 1, etc.). Elements with no Template:Cd specified remain untinted.
    • Template:Nbt A tint source object
      • Template:Nbt: One of Template:Cd.
      • Additional fields depending on value of tint source type.

Tint sources types

constant

Return a constant RGB color.

• Template:Nbt Root constant tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: A packed integer RGB value (e.g. Template:Cd) or an array of decimal RGB values, each between 0.0 and 1.0 (e.g. Template:Cd)

dye

Return value from Template:DCL component or default if not present

• Template:Nbt Root dye tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: An RGB value.

firework

Return average of colors from Template:DCL component or default color if there are none.

• Template:Nbt Root firework tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: An RGB value.

grass

Return grass color at specific climate parameters, based on Template:Cd

• Template:Nbt Root grass tint source object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Positive float between Template:Cd and Template:Cd.
  • Template:Nbt: Positive float between Template:Cd and Template:Cd.

map_color

Return value from Template:DCL component or default color if component is not present.

• Template:Nbt Root map_color tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: An RGB value.

potion

Return color from Template:DCL component:

• if component is present:
  • custom_color value, if there is one present in component
  • default color, if effect list is empty
  • average of effect colors
• else, default color

• Template:Nbt Root potion tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: An RGB value.

team

Returns the team color of context entity, if any. Else, when there is no context entity, entity is not in a team or team has no color, return default.

• Template:Nbt Root team tint source object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Nbt: An RGB value.

custom_model_data

Return value from Template:Cd list in Template:DCL component.

• Template:Nbt Root custom_model_data tint source object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Optional. Index for field in Template:Cd. Default: Template:Cd.
  • Template:NbtTemplate:Nbt: An RGB value.

composite

Render multiple sub-models in the same space.

• Template:Nbt Root composite items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt: List of Items model objects to render.

condition

• Template:Nbt Root condition items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt: type of boolean property. One of Template:Cd.
  • Additional fields depending on value of boolean property type.
  • Template:Nbt: The Items model object when the property is Template:Cd.
  • Template:Nbt: The Items model object when the property is Template:Cd.

Boolean property types

broken

Return Template:Cd if the item is damageable and has only one use remaining before breaking.

No additional fields for this type.

bundle/has_selected_item

Return Template:Cd if bundle is "open", i.e. it has selected item visible in GUI.

No additional fields for this type.

carried

Return Template:Cd if item is carried between slots in GUI.

No additional fields for this type.

component

Uses component Minecraft:data component predicates to match item components.

• additional fields:
  • Template:Nbt: Type of component predicate (member of Template:Cd registry).
  • Template:NbtTemplate:NbtTemplate:Nbt: Value to match against the predicate. The required data structure depends on the predicate.

damaged

Return Template:Cd if the item is damageable and has been used at least once.

No additional fields for this type.

extended_view

Return Template:Cd if player has requested extended details by holding shift key down. Only works when item is displayed in UI. Note: not a keybind, can't be rebound.

No additional fields for this type.

fishing_rod/cast

Return Template:Cd if there is a fishing bobber attached to currently used fishing rod.

No additional fields for this type.

has_component

Return Template:Cd if the given component is present on the item.

• additional fields:
  • Template:Nbt: Component name.
  • Template:Nbt: Optional. If default component value should be handled as "no component". Default: false.

keybind_down

Return Template:Cd if keybind is currently active.

• additional fields:
  • Template:Nbt: Keybind ID, same as value in Template:Cd text component.

selected

Return Template:Cd if item is selected on a hotbar.

No additional fields for this type.

using_item

Return Template:Cd if player is currently using this item.

No additional fields for this type.

view_entity

• When not spectating, return Template:Cd if context entity is the local player entity, i.e. the one controlled by client.
• When spectating, return Template:Cd if context entity is the spectated entity.
• If context entity is not present, will return Template:Cd.

No additional fields for this type.

custom_model_data

Return value from Template:Cd list in Template:DCL component.

• additional fields:
  • Template:Nbt: Optional. Index for field in Template:Cd. Default: Template:Cd.

select

Render an items model based on discrete property.

• Template:Nbt Root select items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt: type of property. One of Template:Cd.
  • Additional fields depending on value of property type.
  • Template:Nbt: List of cases to match.
    • Template:Nbt A case to match
      • Template:NbtTemplate:Nbt: Value to match against property, type depends on property. If a list, will match any value of them.
      • Template:Nbt: The Items model object for this case.
  • Template:Nbt: The Items model object if no valid entry was found. Optional, but will render a "missing" error model if not present.

Property types

block_state

Return value for some property from Template:DCL component.

• additional fields:
  • Template:Nbt: String key to select from component.

Values: Any string.

charge_type

Return charge type stored in Template:DCL component.

No additional fields for this type.

Values:

• Template:Cd: If there are no projectiles or component is not present.
• Template:Cd: If there is at least one firework rocket.
• Template:Cd: Any other case.

component

Return value from a component. If the selected value comes from a registry and the current datapacks does not provide it, the entry will be silently ignored.

• additional fields:
  • Template:Nbt: Namespaced ID of the component type.

Values: Depends on the target component type.

context_dimension

Return the ID of the dimension in context, if any.

No additional fields for this type.

Values: Namespaced dimension ID.

context_entity_type

Return the holding entity type, if present.

No additional fields for this type.

Values: Namespaced entity type ID.

display_context

Return context this item is rendered in.

No additional fields for this type.

Values:

• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd
• Template:Cd

local_time

Returns the current time formatted according to a given pattern. The value is updated every second. For full format documentation for locale, time zone and pattern, see ICU (International Components for Unicode) documentation.

• additional fields:
  • Template:Nbt: Optional. A Unicode locale identifier (LDML 1.7). Defaults to Template:Cd, which results in the "root" locale (a set of defaults, including English names).
    • Template:Cd: English language (used for things like week names), formating as in USA.
    • cs_AU@numbers=thai;calendar=japanese: Czech language, Australian formatting, Thai numerals and Japanese calendar.
  • Template:Nbt: Optional. A time zone code. Defaults to the client timezone. Also see the ICU4J TimeZone documentation.
    • Examples: Template:Cd
  • Template:Nbt: Describes format to be used for time formatting. See the corresponding Unicode Technical Standard for details.
    • Template:Cd: 4-digit year number, then 2-digit month number, then 2-digit day of month number, all zero-padded if needed, separated by Template:Cd.
    • Template:Cd: current time (hours, minutes, seconds), 24-hour cycle, all zero-padded to 2 digits of needed, separated by Template:Cd.

Values: Any string.

main_hand

Return main hand of holding player.

No additional fields for this type.

Values: Template:Cd.

trim_material

Return value of Template:Cd field from Template:DCL component, if present.

No additional fields for this type.

Values: Namespaced ID trim material.

custom_model_data

Return value from Template:Cd list in Template:DCL component.

• additional fields:
  • Template:Nbt: Optional. Index for field in Template:Cd. Default: Template:Cd.

Values: Any string.

range_dispatch

Render an items model based on numeric property. Will select last entry with threshold less or equal to property value.

• Template:Nbt Root range_dispatch items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt: type of numeric property. One of Template:Cd.
  • Additional fields depending on value of numeric property type.
  • Template:Nbt: Optional. Factor to multiply property value with. Default: Template:Cd.
  • Template:Nbt:
    • Template:Nbt An entry object
      • Template:Nbt: Threshold float value to select this entry.
      • Template:Nbt: The Items model object for this threshold.
  • Template:Nbt: The Items model object if no valid entry was found. Optional, but will render a "missing" error model instead.

Numeric property types

bundle/fullness

Return weight of Template:DCL component or Template:Cd if not present.

No additional fields for this type.

compass

Return an angle, scaled from Template:Cd to Template:Cd in x-z plane between holder position and target. If target is not valid (not present, in other dimension or too close to holder position) random value will be returned.

• additional fields:
  • Template:Nbt: One of:
    • Template:Cd: points at world spawn.
    • Template:Cd: points at location stored in Template:DCL component.
    • Template:Cd: points at last player death location.
    • Template:Cd: always return an invalid target.
  • Template:Nbt: Optional. If Template:Cd, value will oscillate for some time around target before settling. Default: Template:Cd.

cooldown

Return remaining cooldown for item, scaled between Template:Cd to Template:Cd.

No additional fields for this type.

count

Return stack size.

• additional fields:
  • Template:Nbt: Optional. Default: Template:Cd.
    • If Template:Cd, return count divided by Template:DCL component, clamped to Template:Cd to Template:Cd.
    • If Template:Cd, return count clamped to Template:Cd to Template:Cd.

crossbow/pull

Return crossbow-specific use time.

No additional fields for this type.

damage

Return value for Template:DCL component or Template:Cd if not present.

• additional fields:
  • Template:Nbt: Optional. Default: Template:Cd.
    • If Template:Cd, return value of damage divided by Template:DCL component, clamped to Template:Cd to Template:Cd.
    • If Template:Cd, return raw value of damage, clamped to Template:Cd to Template:DCL.

time

Return value of an in-game time, scaled between Template:Cd to Template:Cd.

• additional fields:
  • Template:Nbt: Time source to return. One of Template:Cd. For Template:Cd, the source value is the Template:Cd Minecraft:environment attribute divided by 360.0, meaning Template:Cd represents noon and Template:Cd represents midnight. For Template:Cd, the source value is the Template:Cd environment attribute, with Template:Cd mapped to Template:Fraction, Template:Fraction, Template:Fraction, Template:Fraction, Template:Fraction, Template:Fraction, Template:Fraction, and Template:Fraction respectively. In both cases, the source value will default to Template:Cd in locations that don't specify those environment attributes, like Minecraft:the Nether and Minecraft:the End. For Template:Cd, the source value is a new random value every frame.
  • Template:Nbt: Optional. If Template:Cd, source value will be used directly. If Template:Cd, value will oscillate for some time around source value before settling. Default: Template:Cd.

use_cycle

Return remaining use ticks modulo Template:Cd.

• additional fields:
  • Template:Nbt: Optional. Must be positive. Default Template:Cd.

use_duration

Return item use ticks.

• additional fields:
  • Template:Nbt: Optional. If Template:Cd, returned value will be remaining use ticks, if Template:Cd - ticks so far. Default: Template:Cd.

custom_model_data

Return value from Template:Cd list in Template:DCL component or Template:Cd if not present.

• additional fields:
  • Template:Nbt: Optional. Index for field in Template:Cd. Default: Template:Cd.

empty

Does not render anything.

No additional fields for this type.

bundle/selected_item

Render the selected stack in Template:DCL component, if present, otherwise does nothing.

No additional fields for this type.

special

Render a special model.

• Template:Nbt Root special items model object
  • Template:Nbt: Template:Cd
  • Template:Nbt
    • Template:Nbt: type of special model. One of Template:Cd.
    • Additional fields depending on value of special model type.
  • Template:Nbt: Namespaced ID of model in Template:Cd directory, to providing transformations, particle texture and GUI light.

special model types

banner

Render a banner with patterns from Template:DCL component.

• Template:Nbt Root banner special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Optional. Selects a model to be used, one of Template:Cd. Default: Template:Cd.
  • Template:Nbt: Color of the banner base, one of 16 predefined colors.

bell

Render the animated part of a Bell block.

No additional fields for this type.

book

Render the book that normally is a part of Enchanting Table and Lectern.

• Template:Nbt Root book special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Angle (in degrees) between the book cover and the centerline (Template:Cd means closed, Template:Cd means open flat)
  • Template:Nbt: Define the positions of the page inside the book, Template:Cd means that the page is at the leftmost position, Template:Cd at the rightmost position.
  • Template:Nbt: Same values than for page1 field.

chest

Render a single chest.

• Template:Nbt Root chest special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Namespaced ID for the texture in the chests texture atlas without the Template:Cd suffix. By default this includes textures in Template:Cd, without the prefix.
  • Template:Nbt: Optional. Selects a model to be used, one of Template:Cd. Default: Template:Cd.
  • Template:Nbt: Optional. Render the chest in the specified open state, between Template:Cd (fully closed) to Template:Cd (fully open). Default: Template:Cd.

conduit

Render conduit.

No additional fields for this type.

copper_golem_statue

Render a Minecraft:copper golem statue.

• Template:Nbt Root copper_golem_statue special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: One of Template:Cd.
  • Template:Nbt: Namespaced ID for the texture with the Template:Cd suffix.

decorated_pot

Render a decorated pot. Uses values from Template:DCL component.Template:Verify

No additional fields for this type.

end_cube

Render a block-sized Minecraft:starfield cube.

• Template:Nbt Root end_cube special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Select the specific effect to apply between Template:Cd.

head

Render a head.

• Template:Nbt Root head special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: One of Template:Cd.
  • Template:Nbt: Optional. Namespaced ID for the texture, without Template:Cd prefix and Template:Cd suffix.
    • If absent, default texture will be used, depending on Template:Cd field.
  • Template:Nbt: Optional. Controlling head animation if available for this Template:Cd of head (like Piglin ears or Ender Dragon jaw). Default: Template:Cd.
    • The Template:Cd animation is Template:Cd units long. Mouth fully closed at Template:Cd and fully open at Template:Cd <ref name="head_animation">News in Resource Pack Version 46 (1.21.4 Pre-Release 1)</ref>.
    • The Template:Cd ears wiggle out of sync. The left ear period is Template:Cd and right ear period is Template:Cd.<ref name="head_animation"/>

player_head

Render a player head. Use the data into the Template:DCL component to select the texture to render.

No additional fields for this type.

shield

Render a shield. Uses patterns from Template:DCL component and color from Template:DCL component.

No additional fields for this type.

shulker_box

Render a shulker box.

• Template:Nbt Root shulker_box special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Namespaced ID for the texture in the shulker boxes texture atlas without the Template:Cd suffix. By default this includes textures in Template:Cd, without the prefix.
  • Template:Nbt: Optional. Render the shulker box in the specified open state, between Template:Cd (fully closed) to Template:Cd (fully open). Default: Template:Cd.

trident

Render a trident.

No additional fields for this type.

History

Removed special model types

bed

Render one half of a bed. To render both halves, and so the whole bed, use a Template:Cd model.

Version added: 24w45a. Version removed: 26.2 snapshot 3.

• Template:Nbt Root bed special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Select the half to render between Template:Cd.
  • Template:Nbt: Namespaced ID for the texture in the beds texture atlas without the Template:Cd suffix. By default this includes textures in Template:Cd, without the prefix.

standing_sign

Renders a standing sign.

Version added: 24w46a. Version removed: 26.2 snapshot 7.

• Template:Nbt Root standing_sign special type object
  • Template:Nbt: Template:Cd
  • Template:NbtTemplate:Sic<ref name="MC-307498"/>: Optional. Selects a model to be used, one of Template:Cd. Default: Template:Cd.
  • Template:Nbt: One of Template:Cd.
  • Template:Nbt: Optional. Namespaced ID for the texture in the signs texture atlas without the Template:Cd suffix. By default this includes textures in Template:Cd, without the prefix. If present, Template:Cd field is ignored.

hanging_sign

Renders a hanging sign.

Version added: 24w46a. Version removed: 26.2 snapshot 7.

• Template:Nbt Root hanging_sign special type object
  • Template:Nbt: Template:Cd
  • Template:Nbt: Optional. Selects a model to be used, one of Template:Cd. Default: Template:Cd.
  • Template:Nbt: One of Template:Cd.
  • Template:Nbt: Optional. Namespaced ID for the texture in the signs texture atlas without the Template:Cd suffix. By default this includes textures in Template:Cd, without the prefix. If present, Template:Cd field is ignored.