Guides

How to use CustomModelData in a resource pack

CustomModelData lets one vanilla item, such as a stick, look like many different items. A command or plugin gives the item a number, and your resource pack shows a different model for each number. How the pack reads that number changed in Minecraft 1.21.4, so this guide covers both ways.

1. Make the texture and model for the new item

Keep your own files in your own namespace so they never clash with the game's. This example turns a stick into a ruby wand. Add the texture at assets/mypack/textures/item/ruby_wand.png and a model at assets/mypack/models/item/ruby_wand.json:

{
  "parent": "minecraft:item/handheld",
  "textures": {
    "layer0": "mypack:item/ruby_wand"
  }
}

item/handheld holds the item like a tool. Use item/generated for a flat item held like most others, or point to a 3D model you made instead.

2a. Minecraft 1.19 to 1.21.3: add an override

Copy the stick's model to assets/minecraft/models/item/stick.json and add an overrides list:

{
  "parent": "minecraft:item/handheld",
  "textures": {
    "layer0": "minecraft:item/stick"
  },
  "overrides": [
    { "predicate": { "custom_model_data": 1 }, "model": "mypack:item/ruby_wand" },
    { "predicate": { "custom_model_data": 2 }, "model": "mypack:item/emerald_wand" }
  ]
}

An override matches when the item's number is equal to or higher than the one in the predicate, and the last match in the list wins. Keep the list sorted from lowest to highest number, or a lower entry will hide a higher one.

2b. Minecraft 1.21.4 and later: add an item model definition

From 1.21.4 the game picks an item's model through files in assets/<namespace>/items/, and the overrides list is no longer read. Create assets/minecraft/items/stick.json:

{
  "model": {
    "type": "minecraft:range_dispatch",
    "property": "minecraft:custom_model_data",
    "index": 0,
    "entries": [
      { "threshold": 1, "model": { "type": "minecraft:model", "model": "mypack:item/ruby_wand" } },
      { "threshold": 2, "model": { "type": "minecraft:model", "model": "mypack:item/emerald_wand" } }
    ],
    "fallback": { "type": "minecraft:model", "model": "minecraft:item/stick" }
  }
}

range_dispatch uses the entry with the highest threshold that is not above the item's number, and fallback covers sticks without one. In these versions custom model data is a list of numbers, and index picks which one to read.

3. Give yourself the item

The command format depends on the version too:

On a server, plugins and datapacks set the same value; ask whoever runs the server which numbers they use.

4. Test it

Turn the pack on and press F3 + T to reload. If the item shows the purple and black missing texture, the model or texture path is wrong; the game log names what it couldn't find. If it shows a plain stick, check the number and, on 1.21.4 or later, that you used an items/ file rather than overrides.

On 1.21.4 and later you can also skip the number: the minecraft:item_model component points an item straight at a definition, for example /give @s minecraft:stick[minecraft:item_model="mypack:ruby_wand"] reads assets/mypack/items/ruby_wand.json.

Doing the same in MineTexture

In the editor, open an item and add an item rule that matches a custom model data number, then paint its texture or build its model. MineTexture writes the files for the version you chose when you export.