Guides / Building & Resources

自定义模型数据：无需替换即可为物品添加多种模型

物品模型系统取代了旧的 CustomModelData 谓词。本文将介绍文件夹布局、将值映射到模型的 JSON，以及为什么你的材质会显示为紫色方块。

2026-07-11

自定义物品模型允许服务器分发一个“魔杖”，它实际上是一个模型不同的胡萝卜钓竿。其机制已发生变化，但大多数教程仍在描述旧的机制。

发生了什么变化

旧方法 — 基础物品模型文件中的一个 predicate 方块，以 custom_model_data 作为数字键：

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

当前方法 — 一个选择模型的 items/ 定义：

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" } }
    ]
  }
}

fallback 是普通胡萝卜钓竿的默认外观。如果没有它，世界上所有未修改的胡萝卜钓竿都会变成你的魔杖。

文件夹布局

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：

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

请注意，材质路径没有 textures/ 前缀，也没有 .png — 这是导致紫色和黑色方块最常见的原因。

给予物品

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

组件现在接受一个带有类型列表的对象，而不是一个裸整数。custom_model_data=1 是旧语法，它会静默地不执行任何操作。

为什么它会显示为紫色方块

按可能性排序：

1. 材质路径错误 — 包含 textures/ 或 .png，或者文件不在路径指定的位置。
2. 文件名大小写 — 即使你的操作系统不区分大小写，游戏也区分大小写。
3. pack_format 过低 — 资源包已加载，但 items/ 文件夹被忽略。请将格式与你当前的版本匹配。
4. 压缩错误 — pack.mcmeta 必须位于 zip 文件的根目录，而不是 zip 文件内的一个文件夹中。

其他选择器

range_dispatch 上的数字只是一个选项。你还可以根据 minecraft:display_context（手持和画框中的模型不同）、minecraft:using_item 或 minecraft:selected 进行分派 — 这就是弓如何显示拉弓状态的方式。

在自定义模型和物品组件工具中一起构建分派 JSON、模型文件和给予命令。

自定义模型与物品组件工具 →