Skip to content
mcjava-wiki

Predicates

This page will explain how Java Edition resource packs use predicates to display different models for a single item based on select ingame NBT values or client-side-only states.

Types

Custom Model Data

Custom model data can be defined for any item model and uses the NBT tag CustomModelData. Custom model data is simply an intger value, and the predicate value maps directly to its NBT value. Items can be obtained with this nbt tag using the following syntax for the give command:

give @p diamond_axe{CustomModelData:1}

Note that this is the only predicate that can be used on any item model, as it was added to the game specifically for the purpose of custom resoruce pack creation. Other predicate types can only be used in specific circumstances.

Damage and Damaged

Damage and damaged predicates can only be defined for models that have durability. This generally includes tools, weapons, and armor. In the case of armor, it is important to note that the model will not be visible in armor slots. Damage refers to the durability of the item, while damaged refers to weether or not the item can be damaged. For example, an item with unbreaking NBT cannot be damaged.

The predicate damage is a float that is obtained by dividing the total durability of the item, which varies per item, by the current NBT Damage value of the item.

The predicate damaged is technically a boolean represented by 0 or 1. The NBT {Unbreakable:1b} most closely maps to a damaged value of 0, and its inverse a damaged value of 1. However, it is important to note that an item without any NBT Damage, regardless of the state of its Unbreakable NBT, will always map to a damaged value of 0.

Other Predicates

Other predicates are used on an item specific basis, and will be detailed in a later more exhaustive section about predicates:

  • angle (compass, recovery_compass)
  • blocking (shield)
  • broken (elytra)
  • cast (fishing_rod)
  • charged (crossbow)
  • firework (crossbow)
  • pull (crossbow, bow)
  • pulling (crossbow, bow)
  • filled (bundle, map)
  • level (light)
  • throwing (trident)
  • time (clock)
  • tooting (goat_horn)

Usage

Definition

Predicates are defined in an item model via the overrides array as follows. Since these predicates override vanilla items, an overrides array will only be effective for models existing in the minecraft namespace. Take the example of a diamond sword with custom model data, damage, and damaged predicates:

1{
2  "parent": "minecraft:item/handheld",
3  "textures": {
4    "layer0": "minecraft:item/diamond_sword"
5  },
6  "overrides": [
7    {
8      "predicate": {
9        "custom_model_data": 2,
10        "damaged": 0
11      },
12      "model": "minecraft:custom/a"
13    },
14    {
15      "predicate": {
16        "custom_model_data": 5,
17        "damaged": 1
18      },
19      "model": "minecraft:custom/b"
20    },
21    {
22      "predicate": {
23        "damage": 0.00192184497,
24        "damaged": 1
25      },
26      "model": "minecraft:custom/c"
27    },
28    {
29      "predicate": {
30        "damage": 0.00512491992,
31        "damaged": 0
32      },
33      "model": "minecraft:custom/d"
34    },
35    {
36      "predicate": {
37        "damage": 0.00768737988,
38        "damaged": 1
39      },
40      "model": "minecraft:custom/e"
41    },
42    {
43      "predicate": {
44        "damage": 0.00384368994,
45        "custom_model_data": 8,
46        "damaged": 1
47      },
48      "model": "minecraft:custom/f"
49    }
50  ]
51}

Here, within the overrides array, each entry must have a predicate key and a model key. While the predicate key is an object consisting of multiple predicate values, model is a file path that uses standard namespace notation starting from the items folder and excluding the file extension. When no namespace is specified, the minecraft namespace is assumed.

Predicate Resolution

It is important to note that what model will be displayed does depend on the order of entires in the overrides array. Put succinctly:

  • Start at the end of the overrides array.
  • If no value is specified for any given predicate, assume a value of 0.
  • Take the first entry that is less than or equal to the actual state of the item. The actual state may be defined by NBT or some internal client state.

Though these two rules may seem simple, this can become complicated when dealing with predicates like damaged that do not map directly to their equivalent NBT value. This concept will be explored later in the more exhaustive predicates section.

Key Takeaways

  • Predicates allow the display different models for a single item based on select ingame NBT values or client-side-only states
  • The predicate custom model data can be used on any item, the damage and damage predicates can be used on any item with durability, and other predicates exist for use with specific items
  • Predicates are defined in the overrides array of the model JSON
  • Predicates are resolved starting at the end of the overrides array, using the first entry that is less than or equal to the actual state of the item
 Page Contributors
Kas-tle