跳到主要内容

🎨 物品模型定义

入门教程通过一行配置为物品换上了自定义贴图。本章将进一步介绍这项简化配置背后的物品模型系统。

模型与物品模型定义​

这两个词听起来相似，但含义不同：

模型物品模型定义
是什么单个 JSON 文件——几何体、贴图、显示变换一个 JSON 文件，决定渲染哪个（哪些）模型
存放在assets/<ns>/models/assets/<ns>/items/
类比一件衣服一个衣柜，根据场合挑衣服

模型是静态资源，例如 block/cube_all、item/handheld 或从 Blockbench 导出的文件。物品模型定义则负责选择模型，决定物品在手持、物品栏、掉落、受损或蓄力等状态下应如何渲染。

CraftEngine 物品配置中的 model: 字段，写的就是物品模型定义。当你写：

items:
  tutorial:sword:
    material: golden_sword
    texture: tutorial:item/toxic_sword

CraftEngine 生成的物品模型定义会始终使用同一个模型。这是最简单的用法，物品模型定义还支持更复杂的条件与组合。

六种模型类型​

物品模型定义采用树状结构，每个节点都有一个 type。共有以下六种类型：

类型作用
minecraft:model渲染一个静态模型文件
minecraft:composite叠加多层模型
minecraft:condition根据布尔属性在两种模型间切换
minecraft:select根据枚举属性从多个候选中选择
minecraft:range_dispatch根据数值跨越阈值选择模型
minecraft:special渲染硬编码的原版特殊模型（头、旗帜、盾牌……）

示例 1：静态模型​

静态模型始终渲染同一个模型文件：

model:
  type: minecraft:model
  path: tutorial:item/sword

或者缩写：

model: tutorial:item/sword

示例 2：耐久度改变外观​

一把随着磨损出现裂纹的剑，使用 range_dispatch：

model:
  type: minecraft:range_dispatch
  property: minecraft:damage
  scale: 0.25
  entries:
    - threshold: 0.0
      model:
        type: minecraft:model
        path: tutorial:item/sword_pristine
    - threshold: 0.5
      model:
        type: minecraft:model
        path: tutorial:item/sword_damaged
    - threshold: 0.75
      model:
        type: minecraft:model
        path: tutorial:item/sword_broken

scale 划分耐久度比例。耐久度高于 75% 时显示崭新；50–75% 之间出现裂纹；低于 50% 接近断裂。

示例 3：叠加发光效果​

要为宝石叠加静态基底和脉冲光晕，可以使用 composite：

model:
  type: minecraft:composite
  models:
    - type: minecraft:model
      path: tutorial:item/gem_glow
    - type: minecraft:model
      path: tutorial:item/gem_base

光晕层可以使用带透明区域的独立模型，并渲染在基底之上；配合动画贴图即可形成脉冲效果。

示例 4：快捷栏选中发光​

要让物品在快捷栏中被选中时显示不同外观，可以组合使用 condition 和 minecraft:selected：

model:
  type: minecraft:condition
  property: minecraft:selected
  on_true:
    type: minecraft:model
    path: tutorial:item/sword_selected    # 当前选中的快捷栏格子
  on_false:
    type: minecraft:model
    path: tutorial:item/sword_normal      # 背包或其他格子

示例 5：蓄力武器（嵌套）​

对于同时具有三档蓄力状态和受损裂纹的武器，可以在 composite 中嵌套 range_dispatch：

model:
  type: minecraft:composite
  models:
    - type: minecraft:condition
      property: minecraft:damaged
      on_true:
        type: minecraft:model
        path: tutorial:item/damage_overlay
      on_false:
        type: minecraft:empty
    - type: minecraft:range_dispatch
      property: minecraft:use_duration
      scale: 0.33
      entries:
        - threshold: 0.0
          model:
            type: minecraft:model
            path: tutorial:item/mace_idle
        - threshold: 0.33
          model:
            type: minecraft:model
            path: tutorial:item/mace_charging_1
        - threshold: 0.66
          model:
            type: minecraft:model
            path: tutorial:item/mace_charging_2

裂纹渲染在蓄力模型之上，两者可以独立变化。这类效果需要通过可组合的树状结构实现，无法仅靠简单的贴图切换完成。

示例 6：跨维度变色工具​

一把在地狱里外观不同的镐子，使用 select + minecraft:context_dimension：

model:
  type: minecraft:select
  property: minecraft:context_dimension
  cases:
    - when: minecraft:the_nether
      model:
        type: minecraft:model
        path: tutorial:item/pickaxe_nether
    - when: minecraft:the_end
      model:
        type: minecraft:model
        path: tutorial:item/pickaxe_end
  fallback:
    type: minecraft:model
    path: tutorial:item/pickaxe_overworld

物品外观会随玩家所在维度自动切换。再嵌套基于耐久度的 range_dispatch，即可同时按维度和磨损程度改变镐子的外观。

从简单开始

大多数场景无需手写完整的模型树。CraftEngine 提供的 texture:、textures: 和 model: 路径简写已能满足常见需求；只有需要深度定制时才需要树状语法。