Guides / Building & Resources

Dados de modelo personalizados: dando a um item muitos modelos sem substituir nada

O sistema de modelo de item substituiu o antigo predicado CustomModelData. Aqui está o layout da pasta, o JSON que mapeia valores para modelos e por que sua textura aparece como um cubo roxo.

2026-07-11

Modelos de item personalizados permitem que um servidor distribua uma "varinha mágica" que, na verdade, é uma Vara com Cenoura com um modelo diferente. O mecanismo mudou, e a maioria dos tutoriais ainda descreve o antigo.

O que mudou

Antiga forma — um bloco predicate dentro do arquivo de modelo do item base, com chave em custom_model_data como um número:

{ "predicate": { "custom_model_data": 1 }, "model": "item/wand" }

Forma atual — uma definição items/ que seleciona um modelo:

assets/minecraft/items/carrot_on_a_stick.json

{
  "model": {
    "type": "minecraft:range_dispatch",
    "property": "minecraft:custom_model_data",
    "fallback": { "type": "minecraft:model", "model": "minecraft:item/carrot_on_a_stick" },
    "entries": [
      { "threshold": 1, "model": { "type": "minecraft:model", "model": "minecraft:item/wand" } }
    ]
  }
}

O fallback é como uma Vara com Cenoura comum ainda se parece. Sem ele, cada uma não modificada no mundo se transforma em sua varinha.

O layout da pasta

pack.mcmeta
assets/minecraft/
├── items/carrot_on_a_stick.json      the dispatch
├── models/item/wand.json             the model
└── textures/item/wand.png            the texture

models/item/wand.json na sua forma mais simples:

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

Observe que o caminho da textura não tem prefixo textures/ e nem .png — essa é a causa mais comum de um cubo roxo e preto.

Dando o item

/give @p carrot_on_a_stick[custom_model_data={floats:[1]}]

O componente agora aceita um objeto com listas tipadas, não um número inteiro simples. custom_model_data=1 é a sintaxe antiga e silenciosamente não faz nada.

Por que aparece como um cubo roxo

Em ordem de probabilidade:

1. Caminho da textura errado — inclui textures/ ou .png, ou o arquivo não está onde o caminho indica.
2. Caixa do nome do arquivo — o jogo diferencia maiúsculas de minúsculas, mesmo onde seu sistema operacional não o faz.
3. pack_format muito baixo — o pacote carrega, mas a pasta items/ é ignorada. Corresponda o formato à versão em que você está.
4. Compactado errado — pack.mcmeta deve estar na raiz do zip, não dentro de uma pasta dentro do zip.

Outros seletores

range_dispatch em um número é apenas uma opção. Você também pode despachar em minecraft:display_context (modelo diferente na mão versus em um quadro), minecraft:using_item, ou minecraft:selected — que é como um Arco mostra um estado de puxado.

Construa o JSON de despacho, o arquivo de modelo e o comando de entrega juntos nas Ferramentas de Componentes de Modelo e Item Personalizados.

Ferramentas de modelo e componentes de item →