跳到主要内容

🎨 物品模型

上一章创建的物品已经可以使用，但外观仍与原版相同。本章将为它换上自定义外观。

CraftEngine 提供了三种配置模型的方式，从简到繁：

方式写法什么时候用
简化纹理texture: 路径只有一张贴图，其余内容由插件自动处理
自动生成model: + generation:需要指定 parent、多个贴图层、display 变换
外部模型model: 路径已有现成的模型 JSON 文件

⚠️ 本章会修改资源包文件（贴图或模型）。修改后请运行 /ce reload all，而不是 /ce reload config。 仅重载配置不会让贴图变更生效。

模型和贴图的存放位置​

包的 resourcepack/ 结构和原版资源包一样：

resourcepack/assets/tutorial
models
textures

引用时 models/ 和 textures/ 前缀省略：tutorial:item/toxic_sword 在模型上下文里解析为 models/item/toxic_sword.json，在贴图上下文里解析为 textures/item/toxic_sword.png。

⚠️ 贴图必须放在 textures/item/ 或 textures/block/ 下。Minecraft 的贴图图集只加载这两个目录。放在别处（比如 textures/custom/）不会加载，显示为紫黑方格。

⚠️ 模型贴图尺寸必须是 2 的幂：例如16×16、32×48、64×64……不满足此条件的会导致客户端mipmap降级。

准备贴图​

⬇ 下载教程用的剑贴图，放到：

resourcepack/assets/tutorial/textures/item/toxic_sword.png

方式一：使用 texture 快速生成​

这是最简单的写法。CraftEngine 会根据 material 自动选择 parent、生成模型文件并分配 CustomModelData。

items:
  tutorial:toxic_sword:
    material: golden_sword
    data:
      item_name: "<!i><#3CB371>剧毒之剑"
    texture: tutorial:item/toxic_sword

依次运行 /ce reload all 和 /ce item get tutorial:toxic_sword，即可获得使用新贴图的剑。

CraftEngine 会根据 material 判断物品类型并自动选择 parent：golden_sword → handheld（手持工具），paper → generated（平面图标），方块物品 → cube_all。无需手动指定 parent、编写 model 配置段或管理 CustomModelData。

texture: 是单数，用于只有一个状态的物品（大多数物品）。多状态物品（弓、弩、钓鱼竿）需要用 textures:（复数），见方式二的简化写法。

方式二：generation 精确控制​

如果需要自行选择 parent 或设置 display 变换，可以使用 generation 格式进行精确控制。

基本写法​

items:
  tutorial:toxic_sword:
    material: golden_sword
    data:
      item_name: "<!i><#3CB371>剧毒之剑"
    model:
      path: tutorial:item/toxic_sword
      generation:
        parent: minecraft:item/handheld
        textures:
          layer0: tutorial:item/toxic_sword

generation 下各字段：

字段必需说明
parent是要继承的父模型，同时决定可用的贴图变量名
textures否为父模型定义的贴图变量赋值
display否各场景的旋转/平移/缩放
gui_light否GUI 光照：front（扁平）或 side（3D 光照，默认）

常用 parent​

parent适合什么效果
minecraft:item/handheld剑、镐、斧第三人称视角下倾斜手持
minecraft:item/generated食物、材料、锭平面 2D
minecraft:block/cube_all方块六面立方体

⚠️ textures 下的参数名由 parent 决定，不能随意填写。 handheld 和 generated 使用 layer0，cube_all 使用 all。变量名错误会导致模型无法正常显示。选定 parent 后，可以在 misode.github.io/assets/model 中查找对应 JSON，确认其 textures 定义了哪些变量。

texture 和 generation 的关系​

texture: tutorial:item/toxic_sword 等价于：

model:
  path: tutorial:item/toxic_sword
  generation:
    parent: minecraft:item/handheld    # 由 material 自动推断
    textures:
      layer0: tutorial:item/toxic_sword

大多数情况下，使用 texture: 即可。需要更换 parent、使用多个贴图层或添加 display 变换时，再使用 generation。

多状态物品的简化写法​

弓、弩、钓鱼竿等物品有多个状态（待机/拉弓/装填），每个状态对应一张贴图。CraftEngine 提供了 textures:（复数）简化写法：

# 弓——4 个槽位
items:
  tutorial:my_bow:
    material: bow
    textures:
      - tutorial:item/bow              # 待机
      - tutorial:item/bow_pulling_0    # 刚开始拉弓
      - tutorial:item/bow_pulling_1    # 拉至中途
      - tutorial:item/bow_pulling_2    # 完全拉满

⚠️ 槽位的顺序固定，由 material 决定。顺序错误可能导致物品在待机时显示拉满弓弦等错误贴图。

常见 material 的槽位数：

material槽位说明
bow4待机 + 拉弓 0/1/2
crossbow6待机 + 拉弦 0/1/2 + 装箭 + 装烟花
fishing_rod2待机 + 已抛竿
shield2待机 + 格挡中
elytra2完好 + 破损

多状态物品通常使用 textures: 简化写法即可。只有在各状态需要使用不同的 parent 或 display 时，才需要完整的 model: + generation: 写法，详见简化模型参考。

方式三：外部模型文件​

对于从网上下载、使用 Blockbench 制作或购买的现成 .json 模型文件，可以直接引用：

items:
  tutorial:toxic_sword:
    material: golden_sword
    data:
      item_name: "<!i><#3CB371>剧毒之剑"
    model: tutorial:item/toxic_sword

在 model: 后直接填写模型路径，CraftEngine 会使用已有的 JSON 文件，不再生成模型。贴图路径则由模型 JSON 定义。

多状态物品（弓、盾牌等）需要不同状态用不同模型文件时，用 models:（复数），槽位顺序和 textures: 一致：

items:
  tutorial:my_shield:
    material: shield
    models:
      - tutorial:item/shield            # 待机
      - tutorial:item/shield_blocking   # 格挡中

💡 CraftEngine 的 resourcepack/ 就是一个完整的 Minecraft 资源包。可以直接用 Blockbench 打开其中的模型 JSON。文件结构与原版资源包一致，Blockbench 能正确解析贴图路径，便于检查贴图是否正常。

⚠️ 文件名必须满足命名空间路径规范，只能用小写字母、数字、-、_、.、/。大写和特殊字符会导致加载失败。

模型里的贴图路径​

打开一个模型 JSON 文件，textures 部分类似这样：

{
  "textures": {
    "0": "tutorial:item/toxic_sword",
    "particle": "tutorial:item/toxic_sword"
  }
}

"tutorial:item/toxic_sword" 解析到 assets/tutorial/textures/item/toxic_sword.png。

常见问题：

现象原因解决方法
贴图路径包含 C:\Users\... 之类的本地路径Blockbench 中的贴图路径设置错误将 textures 中的路径改为 命名空间:item/文件名，并把 PNG 放到 textures/item/ 下
贴图路径写的是 minecraft:item/xxx用的是原版贴图改用你自己的命名空间，或确保对应贴图文件存在
路径对了但还是紫黑贴图文件不在对应位置或拼写有误检查文件名是否全小写、拼写是否正确

修改模型包的命名空间​

购买或下载的资源包通常使用作者自己的命名空间（如 fantasy_pack）。如果需要改为本教程使用的 tutorial：

  1. 用 VS Code 打开模型 JSON 文件
  2. Ctrl+H 查找替换，把 fantasy_pack: 全部换成 tutorial:
  3. 保存
  4. 把贴图文件从 assets/fantasy_pack/textures/item/ 复制到 assets/tutorial/textures/item/
  5. /ce reload all