Guias / Construção e recursos

Dados de modelo personalizados: vários modelos para um item sem substituir nada

O sistema de modelos de item substituiu o antigo predicado CustomModelData. Veja 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 é a aparência de uma vara com cenoura comum. Sem ele, todas as varas com cenoura não modificadas no mundo se transformariam na 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/ 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 não faz nada silenciosamente.

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. Maiúsculas/minúsculas do nome do arquivo — o jogo diferencia maiúsculas de minúsculas, mesmo que seu sistema operacional não o faça.
3. pack_format muito baixo — o pacote carrega, mas a pasta items/ é ignorada. Corresponda o formato à versão em que você está.
4. Zipado errado — o pack.mcmeta deve estar na raiz do arquivo 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.

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

Ferramentas de modelos e componentes de itens →