Guias / Construção e recursos

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

O sistema de modelos de item substituiu o antigo predicado CustomModelData. Veja a estrutura de pastas, 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

Jeito antigo — 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" }

Jeito 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 que uma Vara com Cenoura comum ainda tem. Sem ele, toda Vara com Cenoura não modificada no mundo é renderizada como o cubo roxo e preto de modelo ausente.

A estrutura de pastas

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 no seu formato mais simples:

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

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

Entregando 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 puro. custom_model_data=1 é a sintaxe antiga, e o comando agora a rejeita como malformada.

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 e minúsculas no nome do arquivo — o jogo diferencia maiúsculas de minúsculas mesmo onde seu sistema operacional não diferencia.
3. pack.mcmeta desatualizado — a versão 26.x exige min_format e max_format; um número de formato atual em um pack_format puro faz o pacote aparecer como incompatível.
4. Zip errado — o pack.mcmeta precisa 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 distribuir com base em minecraft:display_context (modelo diferente na mão versus no suporte), minecraft:using_item, ou minecraft:selected — é assim que um Arco mostra o estado tensionado.

Monte o JSON de distribuição, o arquivo de modelo e o comando de entrega juntos nas Ferramentas de Modelo Personalizado e Componente de Item.

Ferramentas de modelos e componentes de itens →