Custom item textures without replacing vanilla ones: custom model data

Replacing the diamond sword texture changes every diamond sword in the game. Server owners and map makers often want something different: a special sword that looks unique while normal diamond swords stay the same. Minecraft supports this with item model data. This guide explains the idea without going deep into JSON.

The idea

An item in your hand is a base item, for example a stick or a paper. You attach a piece of data to that one item, such as a number. The resource pack says: for a stick with that number, use this texture. Other sticks without the number look normal. A plugin or a command gives the item the number.

Before and after Minecraft 1.21.4

• In 1.14 up to 1.21.3, the number is called custom model data. The pack overrides models/item/stick.json with a list of overrides that map each number to a model.
• In 1.21.4 and newer, items use item model definitions in assets/minecraft/items. An item can also point to any model with the item_model component, which makes custom items much cleaner. Custom model data still exists for choosing between models.

What you need to draw

For a flat item you only need one PNG per item. Give each one a clear name in your own namespace or in a subfolder, such as textures/item/texturecrafter/ruby_ring.png. This is exactly what the Library export does for textures that do not have a vanilla name: it puts them in a subfolder, so you can point your model files at them.

A simple model file

A flat item model says: use the generated item shape and this texture. For 1.13 and newer it looks like this.

{
  "parent": "minecraft:item/generated",
  "textures": {
    "layer0": "minecraft:item/texturecrafter/ruby_ring_ab12"
  }
}

Save it as a .json file under assets/minecraft/models/item and connect it to your item with an override or an item model definition. Free tools like Blockbench can create these files and also build 3D models for larger custom items.

How to give the item the number

On a server, plugins give items their model data. In single player you can use a command that sets the component. Both need the same number or id as in your pack. Keep a short list of your ids to avoid confusion once the pack grows.

Tips

• Use one base item for each group, such as paper for icons and sticks for tools, so the vanilla ones stay untouched.
• Draw custom items in the same style and size as the vanilla ones nearby.
• Test with and without the pack to make sure normal items did not change.