Think about the decision before the file
In 1.21.4+, an item definition is less about writing a long file and more about naming the decision the item is making. Does it always look the same? Does one property choose between states? Does a number cross thresholds? Does a simple true or false check change the model? Once that question is clear, the file shape becomes much calmer.
That is why this builder helps. It does not try to invent the logic for you. It keeps the wrapper small, shows the target path early, and nudges you toward the branch type that matches the job instead of the one that merely looks familiar from older pack workflows.
A quick mental map before you click anything
| Branch | Use it when | Best signal |
|---|---|---|
minecraft:model | The item only needs one fixed appearance. | No decision tree is actually happening. |
minecraft:select | One named property picks between branches. | You can describe the change with labels like pass, relic, broken, ritual. |
minecraft:range_dispatch | A number moves across ordered thresholds. | The item has stages, charge, wear, or progress. |
minecraft:condition | A true or false state changes the result. | The item is selected, being used, damaged, or otherwise binary. |
Worked example: one relic, three visible states
Imagine one story item that should look sealed most of the time, glow during a ritual, and crack after the event. That is not three unrelated files. It is one decision tree. If the state comes from a string-like custom value, you are already in
select territory.The builder lets you keep that tree readable: pick the branch type, lock in the fallback first, then add the named states. The important part is not the typing. The important part is that the team can still explain the definition a week later without reopening three different half-finished notes.
A safe workflow inside the builder
- Start with the file path you want under
assets/<namespace>/items/. - Pick the smallest branch type that genuinely fits the item.
- Define the fallback before adding fancy branches.
- Use the quick starts if you already know you are building a direct model, a state switch, or a threshold ladder.
- Copy the JSON, test one item in game, and only then duplicate the pattern across the pack.
When to switch tools
The item model builder owns the visual definition layer. If you still need the command that gives the item to a player, switch to the custom item builder. If the textures and model files themselves still need to be packed into a browser-made resource pack, finish the job in the pack generator.
That separation is healthy. A cleaner visual definition file is easier to debug when command logic and pack packaging are not all fighting for space in the same moment.
Common mistakes
- Using
selectjust because it feels modern, even though a directmodelfile would be simpler. - Skipping the fallback and making the file harder to read from the very first line.
- Mixing numeric and named expectations in one definition without deciding which property is really in charge.
- Naming the JSON file, the model path, and the internal team label so differently that nobody can tell what belongs together.
- Testing branches only in theory and copying them across many items before checking one live example.
FAQ
Do I always need select when CustomModelData is involved?
No. If the item only has one visual identity, a direct model file is cleaner. Use select when one definition really has to branch into multiple appearances.
When is range_dispatch the better choice?
Whenever the change is ordered and numeric: damage stages, charge levels, progress bars, or any threshold-like state.
Why begin with the fallback?
Because the fallback is the calm default reading of the item. Once that anchor is correct, every other branch becomes easier to evaluate.
Can I keep item commands separate from the model definition?
Yes, and that separation is one of the best parts of the new system. The visual file should not be forced to carry command concerns.
What if I only need a simple custom paper pass?
Then the answer is probably a direct minecraft:model file, not a bigger decision tree. Let the problem stay small when the item is small.