🟰 物品模型

概述

自 Minecraft 1.21.4 起，游戏通过物品模型映射决定物品要渲染的模型。CraftEngine 将这套结构封装为 YAML，物品的 model 字段用于定义其外观。模型映射采用树状结构：每个节点都有一个 type，condition、select、range_dispatch 和 composite 等分支类型还可以嵌套子模型。

Minecraft Wiki | 物品模型映射https://zh.minecraft.wiki/w/物品模型映射

根字段

以下字段直接写在物品根级，与 material、model 和 data 同级，并映射到生成的物品模型 JSON 根级。

字段	类型	默认值	说明
hand_animation_on_swap	bool	true	切换手持物品时是否播放第一人称交换动画
oversized_in_gui	bool	true	若为 true，取消 GUI 槽位裁剪——模型可渲染得比槽位更大
swap_animation_scale	float	1.0	交换动画速度倍率；越大越快

items:
  demo:sword:
    material: diamond_sword
    hand_animation_on_swap: false   # 无交换动画
    oversized_in_gui: true          # 允许超出 GUI 格子边界
    swap_animation_scale: 1.5       # 交换动画速度 ×1.5
    model:
      type: minecraft:model
      path: minecraft:item/custom/sword

提示

model 不需要额外字段时可直接写为路径：

items:
  demo:sword:
    material: diamond_sword
    model: minecraft:item/custom/sword

模型类型

type 省略时默认为 minecraft:model。minecraft: 前缀可省略。

📐 模型按照指定的参数渲染指定的物品模型

🧩 组合将多个模型叠加在一起

⚖️ 布尔条件型计算给定的谓词，选择物品模型映射

✅ 枚举条件型计算枚举属性值并查找，选择物品模型映射

📡 值调配型计算数值并查找数值区间，选择物品模型映射

👻 特殊模型调用游戏的特殊模型渲染物品堆叠

∅ 空模型不渲染任何物品模型

📦 收纳袋选中物品渲染收纳袋内选中的物品堆叠

变换（26.1+）

transformation 可以额外指定展示实体使用的物品模型变换。除 empty 和 bundle/selected_item 外所有类型均可指定。

分解形式接收 4 个字段，按此顺序应用：right_rotation → scale → left_rotation → translation。

# 分解形式
transformation:
  right_rotation: 0,0,0,1 # [x, y, z, w] 四元数
  scale: 1,1,1            # [x, y, z]
  left_rotation: 0,0,0,1  # [x, y, z, w] 四元数
  translation: 0,0,0      # [x, y, z]
  # 旋转也可用轴角度对象形式：
  # right_rotation:
  #   angle: 0.0           # 弧度
  #   axis: 0,1,0          # [x, y, z]

# 矩阵（16 个浮点数，行优先，4 行 × 4 列）
# 等价于 T × L × S × R（与分解形式相同的顺序）
transformation:
  - 1,0,0,0   # 第 0 行
  - 0,1,0,0   # 第 1 行
  - 0,0,1,0   # 第 2 行
  - 0,0,0,1   # 第 3 行

custom_model_data（1.21.4 之前）和 item_model（1.21.4+）是 Minecraft 识别物品渲染模型的两套机制。它们位于物品根级——与 material 和 model 同级。CraftEngine 自动管理两者，通常无需手动设置。

它们是什么

字段	版本	格式	工作原理
custom_model_data	全版本	整数	附加在物品堆叠上。资源包模型 JSON 的 overrides 列表将该数字匹配到模型路径。
item_model	1.21.2+	命名空间 ID	直接指向 assets/<ns>/items/<id>.json。无需 override 查找。

当资源包跨越 1.21.4 分界线时，CraftEngine 会同时生成两者——现代版本用 item_model，老版本用 legacy overrides。

CraftEngine 何时自动生成

对于配置了 model 或 texture 的典型物品：

• custom_model_data——若资源包最低版本低于 1.21.2，或启用了 always-use-custom-model-data，则自动分配。起始编号由 config.yml 中的 item.custom-model-data-starting-value 控制（默认 10000）。
• item_model——若服务端 ≥ 1.21.2 且资源包最高版本 ≥ 1.21.4，则自动从物品 ID 生成（demo:sword → item_model: demo:sword）。只要 custom_model_data 为 0，或启用了 always-use-item-model，就会生成。

何时手动设置

items:
  demo:sword:
    material: diamond_sword
    custom_model_data: 10001     # 强制指定编号
    item_model: demo:sword       # 强制指定路径
    model:
      type: minecraft:model
      path: minecraft:item/custom/sword

场景	设置
需要特定 CustomModelData 编号（如其他插件引用）	custom_model_data: <number>
需要自定义 item_model 路径（不使用从 ID 自动生成的）	item_model: <namespace:path>

config.yml 设置

设置	默认值	作用
item.always-use-item-model	true	即使 custom_model_data 存在也生成 item_model。推荐。
item.always-use-custom-model-data	false	即使仅面向 1.21.2+ 的资源包也强制分配 CustomModelData。
item.always-generate-model-overrides	false	即使仅面向 1.21.4+ 的资源包也强制生成 legacy overrides（对基岩版转换器有用）。
item.custom-model-data-starting-value.default	10000	自动分配的第一个 CustomModelData 编号。
item.custom-model-data-starting-value.overrides.<material>	—	按材质覆盖，如 paper: 20000。
item.client-bound-model	true	付费版专属 将 CustomModelData 和 item_model 保留在客户端，允许在不影响已有物品的情况下动态更新。

提示

绝大多数物品无需手动设置这两项。配置好 model 或 texture，其余交给 CraftEngine。

简化模型

完整的模型定义较为繁琐。只需提供贴图并选择正确的基础材质，CraftEngine 就能根据物品类型自动生成对应的模型结构。

根据你手中已有的资源，有三种用法：

如果只有 PNG 贴图而没有模型 JSON，请填写 texture（单个）或 textures（列表）。CraftEngine 会自动生成模型文件并分配路径。没有特殊模型需求时，建议从这种写法开始。

demo:rod:
  material: fishing_rod
  textures:
    - minecraft:item/custom/rod
    - minecraft:item/custom/rod_cast

如果已经使用 Blockbench 或其他工具制作好模型 JSON，请在 model 或 models 中填写文件路径。CraftEngine 会直接使用这些文件，不再生成模型；多模型的槽位顺序与 textures 相同。

demo:shield_3d:
  material: shield
  models:
    - minecraft:item/custom/shield_3d            # 待机
    - minecraft:item/custom/shield_3d_blocking   # 格挡

你希望 CraftEngine 生成模型 JSON，但输出到你指定的路径——比如你在配置的其他地方引用了这些路径。用 models 列表指定输出位置，用 textures 列表提供纹理。两个列表必须槽位一一对应。

demo:bow:
  material: bow
  models:
    - minecraft:item/custom/my_bow
    - minecraft:item/custom/my_bow_pulling_0
    - minecraft:item/custom/my_bow_pulling_1
    - minecraft:item/custom/my_bow_pulling_2
  textures:
    - minecraft:item/custom/my_bow
    - minecraft:item/custom/my_bow_pulling_0
    - minecraft:item/custom/my_bow_pulling_1
    - minecraft:item/custom/my_bow_pulling_2

如果使用 Blockbench 建模，可以通过 blueprint 为每个模型槽位指定 .bbmodel 文件。CraftEngine 会将各文件转换为原版模型 JSON（包括内嵌贴图），并组装出与 textures 写法相同的模型树。

demo:bow:
  material: bow
  blueprint:
    - bow                   # 待机 —— <资源文件夹>/blueprint/bow.bbmodel
    - bow_pulling_0         # 拉弓 0
    - bow_pulling_1         # 拉弓 1
    - bow_pulling_2         # 拉弓 2

.bbmodel 后缀可省略，路径相对于 blueprint 文件夹（与 configuration、resourcepack 同级）。生成模型的路径默认为 item/ 加上各文件相对 blueprint 文件夹的路径；也可以用 models 列表（槽位顺序一致）自行指定输出路径：

demo:bow:
  material: bow
  blueprint:
    - bow
    - bow_pulling_0
    - bow_pulling_1
    - bow_pulling_2
  models:
    - demo:item/bow
    - demo:item/bow_pulling_0
    - demo:item/bow_pulling_1
    - demo:item/bow_pulling_2

单槽位材质（paper、diamond_sword……）只需一个文件：blueprint: rocket。内嵌贴图会导出为 PNG 并保存在模型同路径下；引用已有文件的贴图保持原引用。详见 Blueprint。

提示

列表顺序非常重要。 每个槽位都有特定含义，并随材质而变化。顺序错误可能导致弓在待机状态下显示拉满时的贴图。

2D 图标或手持工具

普通物品（paper、diamond、gold_ingot …）父模型为 item/generated。工具武器（golden_axe、diamond_sword …）为 item/handheld。一个 texture 即可。

demo:icon:
  material: paper
  texture: minecraft:item/custom/icon

demo:axe:
  material: golden_axe
  texture: minecraft:item/custom/axe

钓鱼竿——2 个槽位

抛出鱼线后显示抛竿模型。

demo:rod:
  material: fishing_rod
  textures:
    - minecraft:item/custom/rod         # 待机
    - minecraft:item/custom/rod_cast    # 已抛竿

鞘翅——2 个槽位

即将损坏时切换到破损纹理。

demo:elytra:
  material: elytra
  textures:
    - minecraft:item/custom/elytra         # 完好
    - minecraft:item/custom/elytra_broken  # 破损

盾牌——2 个槽位

盾牌通常是 3D 模型，所以一般用 models 配合已有的 JSON 文件。

demo:shield:
  material: shield
  models:
    - minecraft:item/custom/shield            # 待机
    - minecraft:item/custom/shield_blocking   # 格挡中

矛——2 个槽位

物品在 GUI 或地面上时用一个模型，玩家手持时用另一个。

demo:spear:
  material: golden_spear
  textures:
    - minecraft:item/custom/spear       # GUI、地面、物品展示框
    - minecraft:item/custom/spear_hand  # 手中持有

弓——4 个槽位

一个待机纹理，三个逐步拉弓阶段。

demo:bow:
  material: bow
  textures:
    - minecraft:item/custom/bow              # 待机，未使用
    - minecraft:item/custom/bow_pulling_0    # 刚开始拉
    - minecraft:item/custom/bow_pulling_1    # 拉至中途
    - minecraft:item/custom/bow_pulling_2    # 完全拉满

弩——6 个槽位

弩包含与弓类似的三个拉弦阶段，另外还有装箭和装载烟花火箭两个槽位。

demo:crossbow:
  material: crossbow
  textures:
    - minecraft:item/custom/crossbow              # 待机，未装填
    - minecraft:item/custom/crossbow_pulling_0    # 开始拉弦
    - minecraft:item/custom/crossbow_pulling_1    # 拉至中途
    - minecraft:item/custom/crossbow_pulling_2    # 完全拉满
    - minecraft:item/custom/crossbow_arrow        # 装填了箭
    - minecraft:item/custom/crossbow_firework     # 装填了烟花火箭

旧版模型

这是用于兼容 Minecraft 1.21.4 之前版本的格式。CraftEngine 会自动将现代模型转换为旧版格式，通常无需手动处理。资源包仅面向 Minecraft 1.21.4+ 时，可以跳过本节。

注意

不推荐日常使用。仅在自动转换产生错误结果时才需要手动指定。

items:
  demo:rod:
    material: fishing_rod
    model:
      type: minecraft:condition
      property: minecraft:fishing_rod/cast
      on_false:
        type: minecraft:model
        path: minecraft:item/custom/rod
      on_true:
        type: minecraft:model
        path: minecraft:item/custom/rod_cast
    legacy_model:
      path: minecraft:item/custom/rod
      generation:
        parent: minecraft:item/fishing_rod
        textures:
          layer0: minecraft:item/custom/rod
      overrides:
        - path: minecraft:item/custom/rod_cast
          predicate:
            cast: 1

提示

blueprint 在 legacy_model 及其每个 overrides 中同样可用——.bbmodel 文件会被转换为该模型，path 作为可选的输出路径。见 Blueprint。