猹件开发组

Appearance

On this page

第一个方块模型 ​

完成后的效果 ​

完成本教程后，你会得到一个名为“蓝色水晶”的模型方块物品。它在背包中显示专用图标，放置后显示客户端模型，破坏时再次掉落为同一个模型方块物品。

方块的模型身份保存在载体物品和载体方块自身可还原的 NBT 中。客户端渲染时读取这份数据，不依赖方块坐标记录，因此区块重新加载、方块移动到其他位置或服务端重启后仍能恢复模型。

开始前准备 ​

  • 服务端已经安装 ChaCore 与 ChaEngine。
  • 测试客户端已经安装正确版本的 ChaEngineMod。
  • 你有一个可用的 GeckoLib .geo.json 模型、一张 PNG 贴图和一张背包图标。
  • 若模型包含动画，再准备对应的 .animation.json。
  • 也可以直接准备一个 Blockbench .bbmodel；它会在客户端读取 Cube、Mesh 和工程内数值动画。

如果尚未完成双端安装，先阅读服务端安装和客户端安装。

准备资源文件 ​

把资源放入每个测试客户端的当前游戏目录：

text
resourcepacks/ChaEngine/model/crystal/
├─ crystal.geo.json
├─ crystal.animation.json
├─ crystal.png
└─ crystal_icon.png

服务端不会分发这些文件。文件名、扩展名和大小写必须与下面的 YAML 完全一致。

编写完整配置 ​

在服务端创建 plugins/ChaEngine/block/crystal.yml：

yaml
blue_crystal:                              # 模型 ID；同类配置中必须唯一
  display: "蓝色水晶"                     # 获取物品和破坏掉落时显示的名称
  model: "crystal/crystal.geo.json"       # 相对于客户端 model/ 的模型路径
  animation: "crystal/crystal.animation.json" # 动画文件；无动画时可删除本行
  texture: "crystal/crystal.png"          # 模型贴图
  item-texture: "crystal/crystal_icon.png" # 背包图标；删除后物品直接渲染模型
  default-animation: "idle"               # 默认循环动画；无默认动画时可删除
  scale: 1.0                               # 模型整体缩放
  position: [0, 0, 0]                     # X、Y、Z 位置偏移
  rotation: [0, 0, 0]                     # X、Y、Z 旋转角度
  collision: [1, 1, 1]                    # X、Y、Z 碰撞体积
  brightness: 15                          # 固定亮度 0-15；删除本行则跟随世界光照

配置顶层键 blue_crystal 就是后续操作使用的模型 ID。路径不包含 resourcepacks/ChaEngine/model/ 前缀。

加载配置并放置 ​

  1. 保存 YAML，并确认缩进只使用空格。
  2. 由管理员执行 /chaengine reload。
  3. 若重载返回模型 ID 或 YAML 错误，先修正后再继续。
  4. 玩家执行 /chaengine block get blue_crystal 获取模型方块。
  5. 手持得到的物品，在允许建造的位置正常放置。
  6. 破坏该方块，确认掉落物仍保留模型身份。

不要用普通玩家头颅代替插件生成的载体物品。只有包含有效 ChaEngine 模型 NBT 的载体才能恢复模型。

本节使用的完整命令：

text
/chaengine reload
/chaengine block get blue_crystal

block get 只能由游戏内玩家执行，生成的载体会放入该玩家的背包。

如何确认成功 ​

  • 背包中的物品名称是“蓝色水晶”，并显示 crystal_icon.png。
  • 放置后看到 crystal.geo.json，而不是普通载体外观。
  • 贴图正确，没有紫黑缺失材质。
  • 配置了 brightness: 15 时，模型在黑暗处仍保持满亮度；删除该字段后应重新跟随世界光照。
  • idle 动画存在时会自动播放。
  • 破坏并重新放置后，仍显示同一个模型。
  • 离开区块再返回，或重启服务端后，模型仍可从方块自身数据恢复。

常见问题 ​

背包图标正常，放置后没有模型：先检查 model、texture 和可选 animation 文件；图标成功只证明 item-texture 可读。

显示模型但动画不动：确认动画文件中存在名称完全一致的 idle；如果模型不需要动画，删除 animation 和 default-animation。

重载后提示找不到模型 ID：检查 crystal.yml 能否被 YAML 正常解析，以及顶层键是否确实是 blue_crystal。

破坏后掉落变成普通物品：确认方块是通过 ChaEngine 生成的模型载体放置，而不是手动修改普通方块或使用其他插件替换。

只有部分玩家看不到：逐个核对这些玩家的 Mod 版本和 resourcepacks/ChaEngine/model/crystal/。

下一步 ​

如果使用 Blockbench 原生工程，把上面的 model 改为 crystal/crystal.bbmodel，并按Blockbench .bbmodel 模型检查资源限制和动画名称。