Item Properties

Item properties are a way for the "properties" of items to be exposed to the model system. An example is the bow, where the most important property is how far the bow has been pulled. This information is then used to choose a model for the bow, creating an animation for pulling it.

An item property assigns a certain float value to every ItemStack it is registered for, and vanilla item model definitions can use these values to define “overrides”, where an item defaults to a certain model, but if an override matches, it overrides the model and uses another. They are useful mainly because of the fact that they are continuous. For example, bows use item properties to define their pull animation. Since the value of the property is a float, it increases continuously from 0 to 1. This allows resource packs to add as many models as they want for the bow pulling animation along that spectrum, instead of being stuck with four “slots” for their models in the animation. The same is true of the compass and clock.

Adding Properties to Items

ItemProperties::register is used to add a property to a specific item. The ResourceLocation parameter is the name given to the property (e.g. new ResourceLocation("pull")). The ItemPropertyFunction is a function that takes the ItemStack, the ClientLevel it’s in, the LivingEntity that holds it, and the int containing the id of the holding entity or 0, returning the float value for the property. Some examples are the pulling and pull properties for Items#BOW, and the several default ones in ItemProperties. For modded item properties, it is recommended that the modid of the mod is used as the namespace (e.g. examplemod:property and not just property, as that really means minecraft:property). There's also another method ItemProperties::registerGeneric that is used to add properties to all items, and it does not take Item as its parameter since all items will apply this property.

Important

Use FMLClientSetupEvent#enqueueWork to proceed with the tasks, since the data structures in ItemProperties are not thread-safe.

ItemPropertyFunction is deprecated by Mojang in favor of using the subinterface ClampedItemPropertyFunction which clamps the result between 0 and 1.

Using Overrides

A good example can be found in model/item/bow.json. For reference, here is a hypothetical example of an item with an examplemod:power property. If the values have no match, the default is the current model.

Important

A predicate applies to all values greater than or equal to the given value.

{
  "parent": "item/generated",
  "textures": {
    "__comment": "Default",
    "layer0": "examplemod:items/example_partial"
  },
  "overrides": [
    {
      "__comment": "power >= .75",
      "predicate": {
        "examplemod:power": 0.75
      },
      "model": "examplemod:item/example_powered"
    }
  ]
}

And here’s a hypothetical snippet from the supporting code. Unlike the older versions (lower than 1.16.x), this needs to be done on client side only because ItemProperties does not exist on server.

public void clientSetup(final FMLCLientSetupEvent event) {
  event.enqueueWork(() ->
  {
    ItemProperties.register(ExampleItems.APPLE, 
      new ResourceLocation(ExampleMod.MODID, "pulling"), (stack, level, living, id) -> {
        return living != null && living.isUsingItem() && living.getUseItem() == stack ? 1.0F : 0.0F;
      });
  });
}