What is CustomModelData?
Added in Minecraft 1.14, CustomModelData allows pack creators to attach different textures or 3D models to one vanilla item by using numeric identifiers.
- Without tags, an iron sword looks like the normal vanilla sword.
- With
CustomModelData: 1, it can look like a katana. - With
CustomModelData: 2, it can render as a 3D chainsaw.
For the server and game mechanics, it is still an iron sword. Only the client-side visual wrapper changes.
If you want to use CustomModelData without wiring everything by hand, the practical pair on this site is the Minecraft Resource Pack Generator for the visual side and the Custom Item Builder for the command side.
How it works
The resource pack uses item model overrides. The base model tells the game to load another model when a specific CustomModelData value is present.
{
"parent": "item/handheld",
"textures": { "layer0": "item/iron_sword" },
"overrides": [
{ "predicate": { "custom_model_data": 1 }, "model": "item/custom_katana" },
{ "predicate": { "custom_model_data": 2 }, "model": "item/custom_chainsaw" }
]
}NBT vs Components
Minecraft 1.20.5 changed item data from old NBT syntax to Data Components. The visual result is similar, but commands changed.
Before 1.20.5
/give @p minecraft:iron_sword{CustomModelData:1} 11.20.5 and newer
/give @p minecraft:iron_sword[minecraft:custom_model_data=1] 1Minecraft Resource Pack Generator accounts for this switch when it shows give commands for your custom items.
Why CustomModelData still matters after the move to components
Many people hear that Minecraft moved away from old NBT-heavy item commands and assume CustomModelData became a historical footnote. In practice, the opposite happened. The visual identity problem is still the same: one vanilla item often has to represent many different tools, props, passes, relics, and shop goods. CustomModelData is still one of the cleanest bridges between that gameplay need and the art layer in the resource pack.
What changed is the surrounding ecosystem. Older packs usually treated one number as everything at once: art hook, internal meaning, documentation, and admin memory aid. Modern setups work better when the jobs are separated. The resource pack decides what should render. The command side decides what the server should trust. Once you think in those layers, CustomModelData stops feeling like random trivia and starts feeling like a useful contract between art and logic.
A practical workflow from artwork to a usable item
1. Start with the visual plan
Decide what the item should actually look like in the player’s hand or inventory. If the object needs a custom icon, texture, or 3D shape, that belongs in the resource pack first. The pack generator helps because it builds the folder structure and the model plumbing without forcing you to hand-wire every file.
2. Give the item a stable hidden identity
The visual hook alone is not enough for a live server. A permit, token, contract, or relic usually also needs a hidden ID that quests, merchants, or admin checks can read reliably. That is where the custom item builder becomes useful: it lets the command side stay readable instead of collapsing into one mystery number.
3. Match the syntax to the Minecraft version
Before 1.20.5, item data lived in older NBT-style syntax. In newer versions, commands moved into components, and in 1.21.4+ the visual side can become even richer with modern item model routes and extended custom model data slots. If the version is wrong, the item can look conceptually correct and still fail in game.
4. Test the item before wiring it into bigger systems
Spawn the item once, verify the name, verify the resource pack model, and only then drop it into villager trades, quest rewards, crates, or scripted checks. That order prevents you from debugging three systems at once when the real problem is still just one broken item.
Common mistakes around CustomModelData
Treating one number as the entire system
The classic mistake is asking one CustomModelData value to carry the art route, the hidden logic, the naming convention, and the team memory all at once. That scales badly. As the item library grows, nobody remembers what the old numbers meant or which ones were safe to reuse.
Building the command before the art path exists
It is much easier to debug an item when the model path, texture intent, and fallback visual are already decided. Otherwise the command can technically work while the player still sees the wrong icon, which creates the feeling that “CustomModelData is broken” when the real issue is the pack layer.
Copying examples across syntax generations
A lot of forum examples still belong to older command eras. If you copy a legacy NBT snippet into a component-based version, or a modern component example into an older environment, the command fails even though the idea is still valid. This is one of the main reasons a visual builder is useful: it keeps the syntax era visible.
Thinking CustomModelData alone is enough for server trust
CustomModelData is primarily about how the item renders. A real RP server often also needs hidden identity, readable naming, or auxiliary data for scripts. The strongest setups let the pack handle appearance and let server-side logic handle validation.
Quick FAQ
Do I still need CustomModelData on new Minecraft versions?
Yes, if one vanilla item should branch into multiple different looks. The surrounding syntax changed, but the underlying visual problem did not disappear.
What is the practical pair on this site for working with it?
Use the resource pack generator when you need the visual side, and use the custom item builder when you need the command and hidden item logic. Together they cover the most common real-world workflow.
Is CustomModelData only for weapons?
No. It is just as useful for permits, guild badges, currency, letters, relics, quest props, tokens, decorative food, ritual items, and merchant stock. Weapons are simply the easiest examples to recognize.
What should I check first if the item does not look right?
Check the pack path, the item model link, the version syntax, and whether the correct value is actually attached to the item. In many cases the concept is fine, but one of those four bridges is missing.