物品模型映射

本文章所述内容仅适用于Java版。

类似于根据方块状态选择不同模型，物品模型也具有类似的条件性选择机制。玩家可通过资源包来定义某堆叠物品在何种情况下应该使用哪种烘焙模型。

定义格式[编辑 | 编辑源代码]

物品模型映射都定义在assets/<命名空间>/items/<物品ID>.json的*model内。每种物品都需要定义其对应的物品模型映射，否则游戏将自动设置此物品的模型为无效模型。

<物品ID>.json文件的JSON格式如下：

JSON文件根元素
- hand_animation_on_swap：（默认为true）玩家在快捷栏切换到此物品堆叠时是否应该渲染切换过渡动画。
- *model：一个物品模型映射。
  - 见下文物品模型映射。

物品模型映射

很多时候，需要根据堆叠物品的某个数据或状态来选取不同烘焙模型。物品模型映射将一个与堆叠物品有关的条件和一个烘焙模型建立关联，从而实现了堆叠物品模型的条件性选取。

物品模型映射的JSON结构如下：

- *type：（命名空间ID）物品模型映射的类型。
- 与类型有关的其他字段。详见下文。

类型[编辑 | 编辑源代码]

物品模型映射有下列类型，不同的映射类型决定了游戏在渲染指定物品堆叠时将使用的物品模型和参数。

命名空间ID	物品模型映射行为
复合物品模型映射
composite	按照数组次序依次渲染物品模型映射
condition	根据指定的物品堆叠，计算给定的谓词，选择物品模型映射
range_dispatch	根据指定的物品堆叠，计算数值并查找数值区间，选择物品模型映射
select	根据指定的物品堆叠，计算属性值并查找枚举，选择物品模型映射
渲染物品模型映射
bundle/selected_item	渲染收纳袋内选中的物品堆叠
empty	不渲染任何物品模型
model	按照指定的参数渲染指定的物品模型
special	使用指定的硬编码渲染器渲染物品

bundle/selected_item[编辑 | 编辑源代码]

此物品模型映射类型会让游戏渲染当前收纳袋内被选中的物品堆叠。

此渲染器要求渲染的物品堆叠必须具有bundle_contents组件，否则这个渲染器不会渲染任何东西。

*model
- *type：bundle/selected_item。

composite[编辑 | 编辑源代码]

此物品模型映射类型会先计算数组内所有物品模型映射，再根据数组次序从后向前依次渲染。

*model
- *type：composite。
- *models：从后向前依次渲染的物品模型映射。
  - ：一个物品模型映射。
    - 递归定义物品模型映射。具体格式详见§ 定义格式。

在原版资源包中，该类型的物品模型映射用于将收纳袋的前、中、后三层纹理进行组合。其中，中间层纹理由bundle/selected_item类型的物品模型映射定义。

示例[显示]

收纳袋物品模型映射JSON文件的部分代码如下，该部分代码会在玩家选取收纳袋中某物品时生效：

            ... 此处省略部分代码
            "type": "minecraft:composite",
            "models": [
              {
                "type": "minecraft:model",
                "model": "minecraft:item/bundle_open_back"
              },
              {
                "type": "minecraft:bundle/selected_item"
              },
              {
                "type": "minecraft:model",
                "model": "minecraft:item/bundle_open_front"
              }
            ]
            ... 此处省略部分代码

condition[编辑 | 编辑源代码]

此物品模型映射类型会先计算物品堆叠内给定的谓词，当属性为真时选择一个物品模型映射，为假时选择另一个。

*model
- *type：condition。
- *on_false：谓词为假时选择的物品模型映射。
  - 递归定义物品模型映射。具体格式详见上文。
- *on_true：谓词为真时选择的物品模型映射。
  - 递归定义物品模型映射。具体格式详见上文。
- *property：（命名空间ID）检查给定的物品模型映射谓词类型。
- 其他元素见下文。

示例1[显示]

收纳袋物品模型映射JSON文件的部分代码如下，根据玩家是否选中收纳袋内物品切换模型：

       ...
        "model": {
          "type": "minecraft:condition",
          "property": "minecraft:bundle/has_selected_item",
          "on_false": {
            "type": "minecraft:model",
            "model": "minecraft:item/bundle"
          },
          "on_true": {
            "type": "minecraft:composite",
            "models": [
              {
                "type": "minecraft:model",
                "model": "minecraft:item/bundle_open_back"
              },
              {
                "type": "minecraft:bundle/selected_item"
              },
              {
                "type": "minecraft:model",
                "model": "minecraft:item/bundle_open_front"
              }
            ]
          }
        },
        ...

示例2[显示]

原版鞘翅物品模型映射JSON文件如下，当鞘翅即将损坏时将更换为破损鞘翅模型：

{
  "model": {
    "type": "minecraft:condition",
    "property": "minecraft:broken",
    "on_false": {
      "type": "minecraft:model",
      "model": "minecraft:item/elytra"
    },
    "on_true": {
      "type": "minecraft:model",
      "model": "minecraft:item/elytra_broken"
    }
  }
}

可用的物品模型映射谓词如下表所示：

命名空间ID	具有附加元素	作用
broken	否	检查物品堆叠是否将要损坏，即当前耐久度只剩下1点；如果物品堆叠不可损坏（没有`max_damage`和`damage`组件，或具有`unbreakable`组件），则返回假
bundle/has_selected_item	否	检查玩家是否选中了此收纳袋内的物品堆叠；如果物品堆叠不包含`bundle_contents`组件则返回假
carried	否	检查玩家是否容器屏幕中使用光标选取了这个物品堆叠
custom_model_data	是	读取物品堆叠的`custom_model_data`组件获取谓词结果
component^{[新增：JE 1.21.5]}	是	检查物品堆叠是否满足指定的数据组件谓词
damaged	否	检查物品堆叠损坏程度（`damage`组件）是否为0；如果物品堆叠不可损坏，则返回假
extended_view	否	检查当前客户端是否按下了`⇧ Shift`且物品在GUI内被渲染
fishing_rod/cast	否	检查钓鱼钩是否已经被抛出游戏先检查玩家是否正在钓鱼，没有钓鱼时直接返回假，再检查钓鱼竿在主手还是副手上，如果都没有握住钓鱼竿默认为副手如果物品堆叠刚好和游戏认为钓鱼竿的位置一致（如钓鱼竿不在双手中，当前物品堆叠在副手上），就返回真
has_component	是	检查物品堆叠是否有给定的物品堆叠组件
keybind_down	是	检查键位绑定是否被按下
selected	否	检查玩家是否在快捷栏内选择了这个物品堆叠
using_item	否	检查物品堆叠是否正在被使用，比如食用食物
view_entity	否	检查持有此物品堆叠的生物是否为当前正在作为摄像机的实体，即非旁观模式下是否为当前玩家，旁观模式下是否为当前进入视角的对应实体

其他带有附加元素的谓词如下文所示：

custom_model_data[编辑 | 编辑源代码]

读取物品堆叠的custom_model_data组件其中的flags，将给定下标的布尔值作为谓词结果。

如果物品堆叠没有custom_model_data组件，或下标超过了flags的长度范围，则返回假。

*model
- 布尔条件型物品模型共通字段[显示]
- *property：custom_model_data。
- index：（值≥0，默认为0）检查给定物品堆叠custom_model_data组件中flags对应下标的元素是否为真。

示例[显示]

自定义模型映射，使用此映射的物品的custom_model_data.flags.[1]若存在且为true时渲染成钻石，否则为铁锭：

模型映射

custom_model_data

渲染结果

{
  "model": {
    "type": "minecraft:condition",
    "property": "minecraft:custom_model_data",
    "index": 1,
    "on_false": {
      "type": "minecraft:model",
      "model": "minecraft:item/iron_ingot"
    },
    "on_true": {
      "type": "minecraft:model",
      "model": "minecraft:item/diamond"
    }
  }
}

{flags:[true,false,true],...}

铁锭

{flags:[true],...}

铁锭

{flags:[false,true,false,false],...}

钻石

component[编辑 | 编辑源代码]

本段落包含会在下一次更新中出现的内容。

这些特性在Java版1.21.5的开发版本中加入。

检查物品堆叠是否满足指定的数据组件谓词。数据组件谓词类型及谓词内容参见物品子谓词。

*model
- 布尔条件型物品模型共通字段[显示]
- *property：component。
- *predicate：指定数据组件谓词类型。
- *value：指定谓词内容。

示例[显示]

自定义模型映射，当使用此映射的附魔书存储了不大于3级的锋利魔咒时渲染成钻石：

{
  "model": {
    "type": "minecraft:condition",
    "property": "minecraft:component",
    "predicate": "minecraft:stored_enchantments",
    "value": [
      {
        "enchantments": "minecraft:sharpness",
        "levels": {
          "max": 3
        }
      }
    ],
    "on_false": {
      "type": "minecraft:model",
      "model": "minecraft:item/enchanted_book"
    },
    "on_true": {
      "type": "minecraft:model",
      "model": "minecraft:item/diamond"
    }
  }
}

has_component[编辑 | 编辑源代码]

检查物品堆叠是否有给定的物品堆叠组件。

*model
- 布尔条件型物品模型共通字段[显示]
- *property：has_component。
- *component：（物品堆叠组件类型）检查物品堆叠是否具有此组件。
- ignore_default：（默认为false）当当前的物品堆叠组件内容与物品默认物品堆叠组件内容一致时是否认为此组件不存在而返回假。

示例[显示]

原版指南针物品模型映射JSON文件的部分代码如下：

{
  "model": {
    "type": "minecraft:condition",
    "property": "minecraft:has_component",
    "component": "minecraft:lodestone_tracker",
    "on_false": {
      ...  当lodestone_tracker组件不存在时，若维度为主世界，则获取获取指南针相对玩家出生点的朝向；否则，获取随机朝向。最后根据朝向选取不同的烘焙模型。
    },
    "on_true": {
      ... 当lodestone_tracker组件存在时，指南针相对磁石的朝向，根据朝向选取不同的烘焙模型。
    }
  }
}

keybind_down[编辑 | 编辑源代码]

检查键位绑定是否被按下。

*model
- 布尔条件型物品模型共通字段[显示]
- *property：keybind_down。
- *keybind：（键位的本地化键名）检查键位绑定是否被按下。

model[编辑 | 编辑源代码]

指定游戏使用哪一个物品模型进行渲染，并且指定各个着色索引使用的颜色。

*model
- *type：model。
- *model：用于渲染的物品模型，游戏解析时转换为assets/<命名空间>/models/<路径>.json。
- tints：（默认为空数组）指定物品模型各个着色索引使用的颜色，数组下标对应着色索引。
  - ：颜色提供器。
    - *type：颜色来源。
      如果type为custom_model_data，游戏将获取物品堆叠的custom_model_data组件信息。
    - *default：当物品堆叠不存在custom_model_data组件，或下标超过colors范围时使用的着色颜色。
      - ：R（红）颜色分量。
      - ：G（绿）颜色分量。
      - ：B（蓝）颜色分量。
    - index：（值≥0，默认为0）将给定物品堆叠custom_model_data组件中colors对应下标的元素作为着色颜色。
      如果type为constant，则使用固定颜色。
    - *value：着色颜色。
      - ：R（红）颜色分量。
      - ：G（绿）颜色分量。
      - ：B（蓝）颜色分量。
      如果type为grass，游戏将按照生物群系着色中的植物颜色算法，使用温度值和降水值计算颜色，颜色图使用grass.png。
    - *downfall：（0≤值≤1）降水值。
    - *temperature：（0≤值≤1）温度值。
      如果type为firework，游戏将使用firework_explosion组件中colors内各个颜色的平均值作为着色颜色。
      
      如果type为dye，游戏将获取物品堆叠的dyed_color组件信息作为着色颜色。
      
      如果type为potion，游戏将使用potion_contents组件中的药水颜色作为着色颜色。
      
      如果type为map_color，游戏将使用map_color组件信息作为着色颜色。
      
      如果type为team，游戏将获取持有此物品堆叠的生物的队伍颜色作为着色颜色。
      
      上述5种类型均使用下列格式。
    - *default：游戏获取不到指定信息时（如不存在对应物品堆叠组件）使用的着色颜色。
      - ：R（红）颜色分量。
      - ：G（绿）颜色分量。
      - ：B（蓝）颜色分量。

示例[显示]

原版已绘制的地图的烘焙模型有两层，分别是底层和图案层。底层固定着色，而图案层根据

map_color值变化，使得探险家地图可以显示与常规地图不同的纹理。

{
  "model": {
    "type": "minecraft:model",
    "model": "minecraft:item/filled_map",
    "tints": [
      {
        "type": "minecraft:constant",
        "value": -1
      },
      {
        "type": "minecraft:map_color",
        "default": 4603950
      }
    ]
  }
}

range_dispatch[编辑 | 编辑源代码]

此物品模型映射类型会先计算并返回物品堆叠内给定的一个数值属性，游戏会按照给定阈值从小到大排序，找到数值属性第一个超过或等于的阈值，并使用对应物品模型映射。如果数值属性小于所有阈值，则使用回落映射。

*model
- *type：range_dispatch。
- *entries：定义各个阈值和对应的物品模型映射，此列表不需要排序，游戏会在运行时对这个列表排序。
  - ：一项阈值和对应的物品模型映射。
    - *model：阈值对应的物品模型映射。
      - 递归定义物品模型映射。具体格式详见上文。
    - *threshold：阈值。
- fallback：回落物品模型映射。如果检查数值小于所有阈值则使用此映射。如果此项不存在，且检查数值小于所有阈值，则使用无效模型。
  - 递归定义物品模型映射。具体格式详见上文。
- scale：（默认为1）与获取的数值属性相乘获得最后的检查数值。
- *property：（命名空间ID）检查给定的物品模型映射数值属性类型。
- 其他元素见下文。

游戏中共有下列物品模型映射数值属性：

命名空间ID	具有附加元素	数值来源
bundle/fullness	否	获取收纳袋的容量，此浮点数只会在0-1之间，如果物品堆叠没有`bundle_contents`组件则返回0
compass	是	获取指南针的指向方向
cooldown	否	获取物品堆叠的冷却程度；如果物品不在玩家物品栏内，则返回0
count	是	获取物品堆叠的物品数量
crossbow/pull	否	弩被拉伸的程度；如果物品堆叠没有`charged_projectiles`组件，或物品堆叠不在任何生物身上，则返回0
custom_model_data	是	读取物品堆叠的`custom_model_data`组件中的floats
damage	是	获取物品堆叠的损坏程度
time	是	获取当前维度时间并归一化，用于时钟的渲染
use_cycle	是	根据物品堆叠使用进度按周期返回浮点数
use_duration	是	获取物品堆叠使用进度

带有附加元素的属性及其附加元素如下所示：

custom_model_data[编辑 | 编辑源代码]

读取物品堆叠的custom_model_data组件中的floats，获取指定下标的浮点数。如果下标超过floats的长度范围，或物品堆叠不存在custom_model_data组件，则返回0。

*model
- 值调配型物品模型共通字段[显示]
- *property：custom_model_data。
- index：（值≥0，默认为0）获取给定物品堆叠custom_model_data组件中floats对应下标的浮点数。

compass[编辑 | 编辑源代码]

读取指南针信息，计算指南针指针摆动进度作为返回值，返回值取值为0-1的闭区间。如果指向目标不存在，或指向目标和当前维度不一致，或当前位置与指向目标的距离小于1e-5时，指针摆动进度会使用随机浮点数。

*model
- 值调配型物品模型共通字段[显示]
- *property：compass。
- *target：指南针指向的目标。
- wobble：（默认为true）摆动进度是否会有额外摆动浮动。如果没有浮动，摆动进度会立刻平滑到当前的正确值，而不是在正确值附近浮动。

target可用值和意义如下：

类型	作用
lodestone	读取物品堆叠的`lodestone_tracker`组件作为指向目标，如果没有此组件则不存在
none	不指向任何目标，指南针的摆动进度将被设置为随机数
spawn	当前维度出生点作为指向目标，如果维度类型natural为`false`则不存在
recovery	将持有此物品堆叠的玩家的上次死亡地点作为指向目标，如果玩家没有死亡过或不在玩家身上，则不存在

示例[显示]

指南针物品模型映射JSON文件的部分代码如下，这段代码会在指南针无lodestone_tracker物品堆叠组件时生效。游戏会获取指南针的指向出生点的数据并乘以32.0，然后和entries中的每一项的threshold进行比对并选择相应烘焙模型。

         ... 此处省略部分代码 
          "model": {
            "type": "minecraft:range_dispatch",
            "property": "minecraft:compass",
            "scale": 32.0,
            "target": "spawn",
            "entries": [
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/compass_16"
                },
                "threshold": 0.0
              },
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/compass_17"
                },
                "threshold": 0.5
              },
              ... 此处省略若干关于threshold的枚举,
              {
                "model": {
                  "type": "minecraft:model",
                  "model": "minecraft:item/compass_16"
                },
                "threshold": 31.5
              }
            ]
          }
          ... 此处省略部分代码

另一段与之相应的代码则表达了当前物品有lodestone_tracker物品堆叠组件时所要使用的烘焙模型：

      ... 此处省略部分代码 
      "type": "minecraft:range_dispatch",
      "property": "minecraft:compass",
      "scale": 32.0,
      "target": "lodestone",
      "entries": [
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/compass_16"
          },
          "threshold": 0.0
        },
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/compass_17"
          },
          "threshold": 0.5
        },
        ... 此处省略若干关于threshold的枚举,
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/compass_16"
          },
          "threshold": 31.5
        }
      ]
      ... 此处省略部分代码

count[编辑 | 编辑源代码]

读取物品堆叠的物品数量作为返回值。如果物品数量大于物品最大堆叠数量，则返回物品最大堆叠数量。

*model
- 值调配型物品模型共通字段[显示]
- *property：count。
- normalize：（默认为true）返回物品数量和物品最大堆叠数量之比，而不是当前的物品数量。

damage[编辑 | 编辑源代码]

读取物品堆叠的损坏值（damage组件）。如果物品没有损坏或无法损坏，则返回0。如果损坏值大于最大耐久度（max_damage组件），则返回最大耐久度。

*model
- 值调配型物品模型共通字段[显示]
- *property：damage。
- normalize：（默认为true）返回物品的损坏进度（即损坏值除以最大耐久度，取值为0-1闭区间），而不是当前的损坏值。

time[编辑 | 编辑源代码]

读取当前维度的时间，计算并平滑模拟时钟摆动进度，将时钟摆动进度作为返回值返回，返回值取值为0-1的闭区间。

*model
- 值调配型物品模型共通字段[显示]
- *property：time。
- *source：时间获取源。可以为daytime（昼夜时间）、random（随机数）或moon_phase（月相）。所有数字均在0到1的闭区间内。
- wobble：（默认为true）摆动进度是否会有额外摆动浮动。如果没有浮动，摆动进度会立刻平滑到当前的正确值，而不是在正确值附近浮动。

时间源source指定为月相moon_phase时的返回值可参考下表：

月相	游戏内天数	返回值
满月	8N+1	0.000
亏凸月	8N+2	0.125
下弦月	8N+3	0.250
残月	8N+4	0.375
新月	8N+5	0.500
蛾眉月	8N+6	0.625
上弦月	8N+7	0.750
盈凸月	8N	0.875

示例[显示]

原版时钟物品模型映射JSON文件如下。当维度为主世界时，根据昼夜时间来选取不同的模型；否则根据随机时间选取模型。

{
  "model": {
    "type": "minecraft:select",
    "property": "minecraft:context_dimension",
    "cases": [
      {
        "model": {
          "type": "minecraft:range_dispatch",
          "property": "minecraft:time",
          "scale": 64.0,
          "source": "daytime",
          "entries": [
            {
              "model": {
                "type": "minecraft:model",
                "model": "minecraft:item/clock_00"
              },
              "threshold": 0.0
            },
            {
              "model": {
                "type": "minecraft:model",
                "model": "minecraft:item/clock_01"
              },
              "threshold": 0.5
            },
            {
              "model": {
                "type": "minecraft:model",
                "model": "minecraft:item/clock_02"
              },
              "threshold": 1.5
            },
            ... 省略若干关于threshold的枚举情况,
            {
              "model": {
                "type": "minecraft:model",
                "model": "minecraft:item/clock_00"
              },
              "threshold": 63.5
            }
          ]
        },
        "when": "minecraft:overworld"
      }
    ],
    "fallback": {
      "type": "minecraft:range_dispatch",
      "property": "minecraft:time",
      "scale": 64.0,
      "source": "random",
      "entries": [
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/clock_00"
          },
          "threshold": 0.0
        },
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/clock_01"
          },
          "threshold": 0.5
        },
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/clock_02"
          },
          "threshold": 1.5
        },
        ... 省略若干关于threshold的枚举情况,
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/clock_00"
          },
          "threshold": 63.5
        }
      ]
    }
  }
}

use_cycle[编辑 | 编辑源代码]

读取当前物品堆叠的剩余使用时间，并对给定的周期取模作为返回值。如果物品堆叠不在任何生物身上，或生物没有使用这个物品堆叠，则返回0。

*model
- 值调配型物品模型共通字段[显示]
- *property：use_cycle。
- period：（值>0，默认为1）周期。

示例[显示]

原版刷子物品模型映射JSON文件如下。这里对物品堆叠的剩余使用时间取关于10.0的模，然后乘以0.1，然后根据三种阈值选取不同烘焙模型。item/brush_brushing_0到item/brush_brushing_2的刷子模型仅改变了第三人称下的模型角度，模拟第三人称下的刷子摆动动画效果。

{
  "model": {
    "type": "minecraft:range_dispatch",
    "period": 10.0,
    "property": "minecraft:use_cycle",
    "scale": 0.1,
    "entries": [
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/brush_brushing_0"
        },
        "threshold": 0.25
      },
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/brush_brushing_1"
        },
        "threshold": 0.5
      },
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/brush_brushing_2"
        },
        "threshold": 0.75
      }
    ],
    "fallback": {
      "type": "minecraft:model",
      "model": "minecraft:item/brush"
    }
  }
}

use_duration[编辑 | 编辑源代码]

读取物品堆叠的使用时间或剩余使用时间作为返回值。如果物品堆叠不在任何生物身上，或生物没有使用这个物品堆叠，则返回0。

*model
- 值调配型物品模型共通字段[显示]
- *property：use_duration。
- remaining：（默认为false）使用物品堆叠的剩余使用时间而非使用时间。

示例[显示]

原版弓物品模型映射JSON文件如下。这里没有设定remaining字段，默认为玩家的拉弓时长。这里指定了use_duration属性，当玩家正在拉弓时，游戏将根据拉弓剩余时间选取不同弓状态下的模型。item/bow_pulling_2模型可表示弓完全拉开，item/bow_pulling_1模型可表示弓半拉开。

{
  "model": {
    "type": "minecraft:condition",
    "property": "minecraft:using_item",
    "on_false": {
      "type": "minecraft:model",
      "model": "minecraft:item/bow"
    },
    "on_true": {
      "type": "minecraft:range_dispatch",
      "property": "minecraft:use_duration",
      "scale": 0.05,
      "entries": [
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/bow_pulling_1"
          },
          "threshold": 0.65
        },
        {
          "model": {
            "type": "minecraft:model",
            "model": "minecraft:item/bow_pulling_2"
          },
          "threshold": 0.9
        }
      ],
      "fallback": {
        "type": "minecraft:model",
        "model": "minecraft:item/bow_pulling_0"
      }
    }
  }
}

select[编辑 | 编辑源代码]

此物品模型映射类型会先计算物品堆叠内给定的一个枚举属性，游戏会使用枚举属性值对应的物品模型映射。如果没有匹配的枚举值，则使用回落物品模型映射。

*model
- *type：select。
- *cases：定义枚举值和对应的物品模型映射。枚举值不能重复出现，否则游戏将报错Duplicate case conditions: <重复的枚举值列表>。
  - ：一项枚举值列表和对应的物品模型映射。
    - *model：阈值对应的物品模型映射。
      - 递归定义物品模型映射。具体格式详见上文。
    - ^{[失效：JE 1.21.5]}^{[新增：JE 1.21.5]}*when：匹配此映射的枚举值。
      - ^{[失效：JE 1.21.5]}^{[新增：JE 1.21.5]}：一项枚举值。
- fallback：回落物品模型映射。如果读取结果不匹配任何一个枚举值，则使用此映射。如果此项不存在，且读取结果不匹配任何一个枚举值，则使用无效模型。
  - 递归定义物品模型映射。具体格式详见上文。
- *property：（命名空间ID）检查给定的物品模型映射枚举属性类型。
- 其他元素见下文。

示例1[显示]

原版指南针JSON文件的部分代码如下。这里首先判断维度是否为主世界，若是，则指定指针朝向为玩家出生点，否则不指定指针朝向，此时指针为随机朝向。

      ...
      "type": "minecraft:select",
      "property": "minecraft:context_dimension",
      "cases": [
        {
          "when": "minecraft:overworld",
          "model": {
            "type": "minecraft:range_dispatch",
            "property": "minecraft:compass",
            "scale": 32.0,
            "target": "spawn",
            "entries": [
              ... 若干关于threshold的枚举...
            ]
          }
        }
      ],
      "fallback": {
        "type": "minecraft:range_dispatch",
        "property": "minecraft:compass",
        "scale": 32.0,
        "target": "none",
        "entries": [
          ... 若干关于threshold的枚举...
        ]
      }
      ...

示例2[显示]

原版锁链靴JSON文件的部分代码如下。这里根据trim组件的纹饰材料来选取不同的烘焙模型，从而实现显示带不同颜色纹饰的锁链靴子物品模型。

{
  "model": {
    "type": "minecraft:select",
    "property": "minecraft:trim_material",
    "cases": [
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/chainmail_boots_quartz_trim"
        },
        "when": "minecraft:quartz"
      },
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/chainmail_boots_iron_trim"
        },
        "when": "minecraft:iron"
      },
      ... 若干关于纹饰材料的枚举...
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:item/chainmail_boots_resin_trim"
        },
        "when": "minecraft:resin"
      }
    ],
    "fallback": {
      "type": "minecraft:model",
      "model": "minecraft:item/chainmail_boots"
    }
  }
}

物品模型映射枚举属性类型如下所示：

命名空间ID	具有附加元素	枚举值格式	枚举来源
block_state	是	字符串	读取物品堆叠的`block_state`组件获取方块状态数据
charge_type	否	字符串	弩内部包含的物品类型，检查物品堆叠的`charged_projectiles`组件如果此组件为空或不存在，则为`none`；如果组件内物品堆叠为烟花火箭，则为`rocket`；其他情况下为`arrow`
component^{[新增：JE 1.21.5]}	是	取决于组件ID	读取物品堆叠的可持久化组件
context_dimension	否	字符串	当前玩家所在维度的命名空间ID
context_entity_type	否		持有此物品堆叠的实体类型
custom_model_data	是		读取物品堆叠的`custom_model_data`组件中的strings
display_context	否		获取当前物品堆叠渲染位置，枚举值见模型 § 渲染变换
local_time	是		读取时间并格式为字符串
main_hand	否		获取玩家的主手是左手（`left`）还是右手（`right`）；如果物品堆叠不在玩家身上，则为null，无法匹配
trim_material	否		读取物品堆叠的`trim`组件并获取盔甲纹饰材料；如果物品堆叠无此组件则为null，无法匹配

带有附加元素的类型如下所示：

block_state[编辑 | 编辑源代码]

读取物品堆叠的block_state组件，并获取指定方块属性的值作为返回值。如果物品堆叠不存在此组件，或方块不具有对应方块属性，则返回null，无法匹配。

*model
- 枚举条件型物品模型共通字段[显示]
- *property：block_state。
- *block_state_property：获取方块的指定方块属性。

示例[显示]

原版蜂巢、蜂箱物品模型映射文件就利用该属性来根据honey_level方块状态显示不同烘焙模型。如下两个烘焙模型仅纹理有所差别，实现了蜂巢蜜满和未满时分别显示不同纹理。

{
  "model": {
    "type": "minecraft:select",
    "block_state_property": "honey_level",
    "cases": [
      {
        "model": {
          "type": "minecraft:model",
          "model": "minecraft:block/bee_nest_honey"
        },
        "when": "5"
      }
    ],
    "fallback": {
      "type": "minecraft:model",
      "model": "minecraft:block/bee_nest_empty"
    },
    "property": "minecraft:block_state"
  }
}

component[编辑 | 编辑源代码]

本段落包含会在下一次更新中出现的内容。

这些特性在Java版1.21.5的开发版本中加入。

读取物品堆叠的可持久化组件数据，获取此组件的数据作为返回值。指定不可持久化的组件或枚举值不符合对应组件的数据要求时此模型映射会直接加载失败。

*model
- 枚举条件型物品模型共通字段[显示]
- *property：component。
- *component：获取物品堆叠的指定组件。

custom_model_data[编辑 | 编辑源代码]

读取物品堆叠的custom_model_data组件中的strings，获取指定下标的字符串。如果下标超过strings的长度范围，或物品堆叠不存在custom_model_data组件，则返回null，无法匹配。

*model
- 枚举条件型物品模型共通字段[显示]
- *property：custom_model_data。
- index：（值≥0，默认为0）获取给定物品堆叠custom_model_data组件中strings对应下标的字符串。

local_time[编辑 | 编辑源代码]

读取当前时间，并根据指定时区、地区设置和日期格式获得日期字符串。此字符串每秒最多获取一次。

*model
- 枚举条件型物品模型共通字段[显示]
- *property：local_time。
- locale：（默认为空字符串）时间格式化为字符串时使用的地区设置。格式可参照此文档和RFC3066。
- *pattern：根据时区获取当前时间后，游戏将时间格式化为字符串的日期格式。日期格式可参照此文档。
- time_zone：（默认为系统设置的时区）获取时间使用的时区。格式可参照此文档和此条目。

示例[显示]

原版箱子的物品模型JSON文件如下。这里pattern为MM-dd，表示“月-日”格式。通过when设定仅在每年12月24到26日使用圣诞箱子模型，否则使用普通箱子模型。

{
  "model": {
    "type": "minecraft:select",
    "pattern": "MM-dd",
    "property": "minecraft:local_time",
    "cases": [
      {
        "model": {
          "type": "minecraft:special",
          "base": "minecraft:item/chest",
          "model": {
            "type": "minecraft:chest",
            "texture": "minecraft:christmas"
          }
        },
        "when": [
          "12-24",
          "12-25",
          "12-26"
        ]
      }
    ],
    "fallback": {
      "type": "minecraft:special",
      "base": "minecraft:item/chest",
      "model": {
        "type": "minecraft:chest",
        "texture": "minecraft:normal"
      }
    }
  }
}

special[编辑 | 编辑源代码]

调用游戏的硬编码渲染器渲染物品堆叠。物品堆叠渲染时的渲染变换、粒子纹理变量等可以从物品模型中获取。

*model
- *type：special。
- *base：（命名空间ID）硬编码渲染器使用的基础物品模型。游戏会读取物品模型中的渲染变换、GUI光照和粒子纹理变量。
- *model：硬编码渲染的模型。
  - *type：（命名空间ID）使用的硬编码渲染器。
  - 其他元素见下文。

游戏内包含下列硬编码渲染器：

命名空间ID	具有附加元素	渲染内容
bed	是	渲染床
banner	是	渲染旗帜
conduit	否	渲染潮涌核心
chest	是	渲染箱子
decorated_pot	否	渲染饰纹陶罐，四个面取决于`pot_decorations`组件
hanging_sign	是	渲染悬挂式告示牌
head	是	渲染生物头颅
shulker_box	是	渲染潜影盒
shield	否	渲染盾牌，底色和图案取决于`base_color`和`banner_patterns`组件
standing_sign	是	渲染告示牌
trident	是	渲染三叉戟

bed[编辑 | 编辑源代码]

根据指定的纹理渲染床。

*model
- *type：bed。
- *texture：（命名空间ID）渲染床使用的纹理。游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/bed/<路径>.png。

banner[编辑 | 编辑源代码]

根据底色和banner_patterns物品堆叠组件渲染旗帜。

*model
- *type：banner。
- *color：旗帜底色，可用枚举值见颜色。

chest[编辑 | 编辑源代码]

根据指定的纹理和开合程度渲染箱子。

*model
- *type：chest。
- openness：（默认为0）箱子打开的程度。
- *texture：（命名空间ID）渲染箱子使用的纹理。游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/chest/<路径>.png。

hanging_sign[编辑 | 编辑源代码]

根据指定的纹理渲染悬挂式告示牌。

*model
- *type：hanging_sign。
- texture：（命名空间ID）渲染悬挂式告示牌使用的纹理，如果此项不存在则根据悬挂式告示牌类型选择纹理，游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/signs/hanging/<路径>.png。
- *wood_type：悬挂式告示牌类型，可以为acacia、bamboo、birch、cherry、crimson、dark_oak、jungle、mangrove、oak、pale_oak、spruce和warped。

head[编辑 | 编辑源代码]

按照指定的头颅类型渲染生物头颅。

*model
- *type：head。
- animation：（默认为0）头颅动画进度，控制龙首和猪灵的头渲染时动态部分的动画进度。此值仅当*kind为dragon或piglin时才有实际作用。
- *kind：头颅类型，可以为creeper、dragon、piglin、player、skeleton、wither_skeleton和zombie。此项决定了游戏使用哪种动态模型渲染。
- texture：（命名空间ID）使用指定的纹理渲染对应的头颅，游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/<路径>.png。当*kind为player时，此项会覆盖profile物品堆叠组件的设置值。

shulker_box[编辑 | 编辑源代码]

根据指定的纹理、开合程度和方向渲染潜影盒。

*model
- *type：shulker_box。
- openness：（默认为0）潜影盒打开的程度。
- orientation：（默认为up）潜影盒的方向，可以为up、down、east、south、west和north。
- *texture：（命名空间ID）渲染潜影盒使用的纹理。游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/shulker/<路径>.png。

standing_sign[编辑 | 编辑源代码]

根据指定的纹理渲染告示牌。

*model
- *type：standing_sign。
- texture：（命名空间ID）渲染告示牌使用的纹理，如果此项不存在则根据告示牌类型选择纹理，游戏在渲染时将纹理解析为assets/<命名空间>/textures/entity/signs/<路径>.png。
- *wood_type：告示牌类型，可以为acacia、bamboo、birch、cherry、crimson、dark_oak、jungle、mangrove、oak、pale_oak、spruce和warped。

历史[编辑 | 编辑源代码]

Java版
1.21.4	24w45a	加入了物品模型映射。
	24w46a	加入了`local_time`枚举属性和`keybind_down`布尔属性以分别代替`xmas`和`shift_down`布尔值属性。
		加入了`holder_type`枚举属性。
		加入了`standing_sign`和`hanging_sign`硬编码渲染器。
		为`head`硬编码渲染器加入了可选字段texture。
	pre1	向物品模型映射加入了hand_animation_on_swap字段。
		加入了`empty`类型物品模型映射。
		加入了`team`颜色来源。
		为`head`硬编码渲染器加入了可选字段animation。
		加入了布尔属性`view_entity`。
		加入了枚举属性`context_dimension`，并将`holder_type`重命名为`context_entity_type`。
		移除了数值属性`time`的natural_only字段，并加入了source字段。
		向数值属性`compass`的target字段加入了可选值`none`。
Java版（即将到来）
1.21.5	25w03a	加入了`component`枚举属性。
	25w04a	加入了`component`布尔属性。
	25w04a	现在枚举属性`component`的枚举值若来自注册表且当前数据包并未提供该值，则其将被静默忽略而不是使模型映射加载失败。

导航[编辑 | 编辑源代码]

物品模型映射

目录

定义格式[编辑 | 编辑源代码]

类型[编辑 | 编辑源代码]

bundle/selected_item[编辑 | 编辑源代码]

composite[编辑 | 编辑源代码]

condition[编辑 | 编辑源代码]

custom_model_data[编辑 | 编辑源代码]

component[编辑 | 编辑源代码]

has_component[编辑 | 编辑源代码]

keybind_down[编辑 | 编辑源代码]

model[编辑 | 编辑源代码]

range_dispatch[编辑 | 编辑源代码]

custom_model_data[编辑 | 编辑源代码]

compass[编辑 | 编辑源代码]

count[编辑 | 编辑源代码]

damage[编辑 | 编辑源代码]

time[编辑 | 编辑源代码]

use_cycle[编辑 | 编辑源代码]

use_duration[编辑 | 编辑源代码]

select[编辑 | 编辑源代码]

block_state[编辑 | 编辑源代码]

component[编辑 | 编辑源代码]

custom_model_data[编辑 | 编辑源代码]

local_time[编辑 | 编辑源代码]

special[编辑 | 编辑源代码]

bed[编辑 | 编辑源代码]

banner[编辑 | 编辑源代码]

chest[编辑 | 编辑源代码]

hanging_sign[编辑 | 编辑源代码]

head[编辑 | 编辑源代码]

shulker_box[编辑 | 编辑源代码]

standing_sign[编辑 | 编辑源代码]

历史[编辑 | 编辑源代码]

导航[编辑 | 编辑源代码]

导航菜单