猹件开发组

Appearance

On this page

第一个物品模型 ​

完成后的效果 ​

完成后，你会得到一个不可放置的“青铜护符”。本教程填写 item-texture，所以它在背包、手持、掉落物和展示框中都使用带轻微厚度的平面贴图；它不会像模型方块那样放置到世界中。

开始前准备 ​

  • 服务端已安装 ChaCore 与 ChaEngine。
  • 客户端已安装对应版本的 ChaEngineMod。
  • 准备模型、贴图、可选动画和可选背包图标。
  • 选定一个不可放置的原版物品作为载体；本教程使用 minecraft:paper。

准备资源文件 ​

在每个客户端放置：

text
resourcepacks/ChaEngine/model/charm/
├─ charm.geo.json
├─ charm.animation.json
├─ charm.png
└─ charm_icon.png

编写完整配置 ​

在服务端创建 plugins/ChaEngine/item/charm.yml：

yaml
bronze_charm:                              # 物品模型 ID
  display: "青铜护符"                     # 物品显示名
  material: "minecraft:paper"             # 不可放置的原版载体；省略时默认为 paper
  model: "charm/charm.geo.json"           # 相对于客户端 model/ 的模型文件
  animation: "charm/charm.animation.json" # 可选；无动画时删除本行
  texture: "charm/charm.png"              # 模型贴图
  item-texture: "charm/charm_icon.png"    # 可选背包图标
  default-animation: "idle"               # 可选默认动画
  scale: 1.0                               # 模型缩放
  position: [0, 0, 0]                     # X、Y、Z 位置偏移
  rotation: [0, 0, 0]                     # X、Y、Z 旋转角度

item-texture 决定物品场景的显示方式：

  • 保留该字段时，背包、快捷栏、第一/第三人称手持、掉落物与展示框都使用指定 PNG 生成的平面物品。
  • 删除该字段时，上述场景直接渲染三维模型。

平面物品会按 PNG 中所有 Alpha 不为零的像素生成轮廓侧面；完全透明的像素不会形成侧面。

加载并获取物品 ​

  1. 保存 charm.yml。
  2. 由管理员执行 /chaengine reload。
  3. 把 <玩家名> 替换为在线玩家的精确名称，再执行 /chaengine item give bronze_charm <玩家名>。
  4. 把物品依次放在背包、快捷栏、主手和副手中观察。

本节使用的完整命令：

text
/chaengine reload
/chaengine item give bronze_charm <玩家名>

如何确认成功 ​

  • 物品名显示为“青铜护符”。
  • 背包和快捷栏显示 charm_icon.png。
  • 第一人称与第三人称手持时显示带厚度的 charm_icon.png，左右手朝向正确。
  • 右键不会把它作为方块放入世界。
  • idle 存在时正常播放；删除两个动画字段后仍能静态显示。

常见问题 ​

出现原版纸张外观：确认物品是通过 /chaengine item give bronze_charm <玩家名> 生成，并检查客户端是否已收到配置。

所有物品场景都缺失：填写 item-texture 后只检查 model/charm/charm_icon.png；删除该字段后再检查三维模型与贴图。

图标边缘出现底色：确认 PNG 真正包含透明通道，不要只在绘图软件中显示棋盘格背景。

物品可以放置：改用不可放置的 material。教程使用 minecraft:paper，不要换成方块物品。

位置或朝向不合适：先小幅调整 position、rotation 和 scale；它们是该物品模型的统一配置，不要假设存在未公开的分场景变换字段。

下一步 ​

三维物品也可以把 model 改为 charm/charm.bbmodel；内嵌或相对路径纹理、Mesh 和数值骨骼动画的规则见Blockbench .bbmodel 模型。