跳到主要内容

🟰 物品模型

概述​

自 1.21.4 起，Minecraft 使用物品模型映射控制物品渲染哪个模型。CraftEngine 将其封装为 YAML —— model 字段决定了物品的一切外观。模型是一棵树：每个节点有一个 type，分支类型（condition、select、range_dispatch、composite）可嵌套子模型。

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

根字段​

以下字段写在物品层级 —— 与 material、model、data 同级。它们映射到生成的物品模型映射 JSON 根级。

字段类型默认值说明
hand_animation_on_swapbooltrue切换手持物品时是否播放第一人称交换动画
oversized_in_guibooltrue若为 true，取消 GUI 槽位裁剪——模型可渲染得比槽位更大
swap_animation_scalefloat1.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_model1.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
场景设置
需要特定 CMD 编号（如其他插件引用）custom_model_data: <number>
需要自定义 item_model 路径（不使用从 ID 自动生成的）item_model: <namespace:path>

config.yml 设置​

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

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

简化模型​

亲手写出完整模型定义很繁琐。CraftEngine 可以替你搞定——只需提供纹理并选择正确的基础材质。它会根据你基于的物品自动构建正确的模型结构。

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

你只有纹理 PNG，没有模型 JSON。给 CraftEngine 填入 texture（单个）或 textures（列表），它会自动生成模型文件并分配路径。这是最常见的场景——没有特殊需求就从这里开始。

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

你已经在 BlockBench（或其他工具）中制作好了模型 JSON 文件。填入 model 或 models 字段，附带你的 JSON 路径。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
提示

顺序至关重要。 列表中的每个槽位都有特定含义，且会根据材质而变化。顺序搞错了，你的弓会在待机时显示拉满的纹理。

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     # 装填了烟花火箭

旧版模型​

1.21.4 之前的兼容格式。CraftEngine 会自动将现代模型转换为旧版格式——你通常不需要手动处理。如果只面向 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