指南 / 建筑与资源

自定义模型数据：让一个物品拥有多种模型而不替换任何内容

物品模型系统取代了旧的 CustomModelData 谓词。以下是文件夹结构、将数值映射到模型的 JSON，以及为什么你的纹理显示为紫色方块，新写法用 range_dispatch 加 threshold 选模型，取代旧版基于数值的写法。

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.mcmeta——26.x 需要 min_format 和 max_format；在裸 pack_format 中使用当前格式号会使资源包显示为不兼容。
4. 压缩方式错误——pack.mcmeta 必须位于 zip 的根目录，而不是 zip 内某个文件夹里。

其他选择器

以数字为键的 range_dispatch 只是其中一种选项。你还可以根据 minecraft:display_context（手持与放在展示框中显示不同模型）、minecraft:using_item 或 minecraft:selected 进行分发——弓就是通过这种方式显示拉弓状态的。

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

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