The problem with number-only systems
Numbers are fine for rendering, but bad for memory. Staff documents turn into giant translation tables, old IDs get reused by mistake, and debugging a broken quest reward becomes slower than it should be.
Keep a readable identity layer
Even if the visual model pipeline still points to a number, your server workflow should also keep a string ID such as rp.guard.badge_bronze or quest.chapter3.letter_mayor. That string can live in minecraft:custom_data while the visible art keeps using custom_model_data.
A safe combined pattern
components:{
"minecraft:custom_model_data":2047,
"minecraft:custom_data":{
item_id:"rp.guard.badge_bronze",
issue:"capital_watch"
}
}Why this scales better
| Question | Number only | Number + string ID |
|---|---|---|
| "What is item 2047?" | Search a spreadsheet, hope it is current. | Read rp.guard.badge_bronze directly from the item. |
| Two staff reuse a value by accident | Silent visual collision, discovered in play. | Duplicate string ID is easy to grep for before it ships. |
| A trade or quest needs to check the item | Match on the model number, which also changes if the art changes. | Match on the stable string, independent of any future re-texture. |
- The art team can search readable IDs in docs.
- Quest logic becomes easier to audit.
- Old items are less likely to be confused with test assets.
- Trades and rewards can validate the hidden string, not only the visible model.
Suggested naming strategy
- Use namespaces by system:
rp.,quest.,shop.,faction. - Keep tokens readable and stable.
- Avoid spaces and translated names in the hidden ID.
- Let the visible text be local and pretty, and let the hidden ID stay boring.
This is the same instinct behind a full naming system for custom items in general — see how to name custom Minecraft items without duplicates for the broader pattern (category + family + variant) that a string ID like this one is meant to slot into.
Where the number still belongs
The numeric model hook still matters for rendering and pack organization. The trick is not to throw it away, but to stop pretending that one integer should also be your only admin-friendly item identity.
Recommended server workflow
- Assign the art-facing model value.
- Assign the logic-facing string ID.
- Use the string ID in documentation, shops, and validation checks.
- Keep the number mainly as a pack rendering detail.
FAQ
Does adding custom_data slow down rendering?
No. custom_model_data still drives the model lookup exactly as before; custom_data is inert extra data the client does not need to render anything, so it costs nothing visually.
Can I add a string ID to items that already only have a number?
Yes, retroactively is fine. Existing items keep working with just the number; you only gain the readable ID on items you update or reissue going forward.
Should the string ID ever be shown to players?
Generally no — keep it in custom_data, which is not shown in the tooltip by default. The visible name and lore stay purely cosmetic and can change freely without touching the hidden identity.
What if two different items legitimately share one model number?
That is exactly the case a string ID is for. The model number can be reused for visually identical items; the string ID is what tells your systems they are not the same object.
Where to go next
For the naming convention itself — category, family, variant — see how to name custom Minecraft items without duplicates. To assemble the full give command around an item like this, the custom item catalog keeps IDs, display names, and CustomModelData slots together in one place.