猹件开发组

Appearance

On this page

物品模型 ​

物品模型用于制作不可放置的自定义物品。服务端把物品模型 ID 写入物品自身 NBT；客户端按该 ID 查找同步配置并选择平面贴图或三维模型渲染。

完整配置 ​

文件位置：plugins/ChaEngine/item/*.yml

yaml
bronze_charm:                               # 配置节点名；默认作为物品模型 ID
  display: "青铜护符"                      # 物品显示名
  material: "minecraft:paper"              # 原版载体，默认是 paper
  model: "charm/charm.geo.json"            # 三维模型路径
  animation: "charm/charm.animation.json"  # 可选动画文件
  texture: "charm/charm.png"               # 三维模型贴图
  item-texture: "charm/charm_icon.png"     # 可选平面物品贴图
  default-animation: "idle"                # 可选默认动画
  match:                                     # 可选；没有模型 NBT 时按名称或 Lore 自动匹配
    - "name#equal#青铜护符"
    - "lore#contains#遗迹掉落"
  priority: 50                               # 多个物品模型同时匹配时，数值大的优先
  scale: 1.0                                # 三维模型缩放
  position: [0, 0, 0]                      # 三维模型位置偏移
  rotation: [0, 0, 0]                      # 三维模型旋转角度

字段说明 ​

字段必填默认值说明
display建议空服务端生成物品时使用的显示名
material否minecraft:paper原版载体物品；建议选择不可放置物品
model条件必填无未使用 item-texture 时需要的三维模型路径
animation否空三维模型动画路径
texture条件必填无三维模型贴图路径
item-texture否空填写后改用平面贴图物品渲染
default-animation否空三维模型的默认动画 ID
match否空按物品名称或 Lore 自动匹配该模型；规则与物品背景一致
priority否0多个自动匹配配置同时命中时，数值较大的优先
scale否1.0三维模型统一缩放
position否[0, 0, 0]三维模型 X、Y、Z 偏移
rotation否[0, 0, 0]三维模型 X、Y、Z 旋转

配置至少要有一条可用渲染路径：item-texture，或者有效的 model 与 texture。不要为不存在的公开字段编写分场景变换。

运行规则 ​

基础材质与放置行为 ​

material 决定服务端实际生成哪种原版物品，省略时为纸。ChaEngine 的物品模型不会写入模型方块数据；如果把 material 配成可放置的原版方块物品，右键只会遵循该原版物品行为，不会生成 ChaEngine 模型方块。因此推荐坚持使用不可放置载体。

模型 ID 与自动匹配 ​

由 ChaEngine 创建、已经带有物品模型 ID 的物品始终优先按该 ID 渲染。普通物品没有模型 ID 时，客户端才按 match 检查名称和 Lore。

match 使用与物品背景相同的 字段#操作符#值 语法：多行之间是“或”，同一行用英文逗号分隔的条件之间是“且”。支持 name、lore 与 start、end、equal、notEqual、contains、notContains。

多个物品模型同时匹配时，先使用 priority 较大的配置；优先级相同才按配置加载顺序决定。重叠规则应设置明确且不同的优先级。

直接绑定 MythicMobs 物品 ​

需要让 MythicMobs 物品固定使用某个 ChaEngine 模型时，可以在物品配置中加入嵌套的 ChaEngine.model：

yaml
CrystalCharm:
  Id: PAPER
  Display: "水晶护符"
  ChaEngine:
    model: bronze_charm  # 来自 plugins/ChaEngine/item/*.yml 的模型 ID，不是文件路径

绑定发生在 MythicMobs 已经生成的同一个物品实例上，因此材质、数量、显示名、Lore、附魔、耐久和其他 NBT 都会保留。写入的 ChaEngine.item 优先于名称或 Lore 的 match；只有之后新生成的物品会读取这一段，已经发出的物品不会批量迁移。缺失、空白或未知模型 ID 不会取消掉落或替换物品，服务端会针对同一 MythicMobs 类型和 ID 限制一次警告。

辅助命令 ​

text
/chaengine item get <id>
/chaengine item give <id> <player>
/chaengine item give <id> <player> <amount>

item get 由游戏内玩家执行并发给自己；两个 item give 入口需要管理员或控制台，<player> 是在线玩家的精确名称。<amount> 无法解析或小于 1 时按 1 处理。完整返回结果见命令参考。

平面贴图与三维模型 ​

  • 填写 item-texture：所有受支持的物品显示场景使用该 PNG 构建轻微厚度的平面网格。
  • 省略 item-texture：背包、快捷栏、第一/第三人称手持、掉落物和展示框直接渲染 model。

平面网格包含正反面，并沿所有 Alpha 不为零的像素边界生成侧面。完全透明的贴图会得到空网格并输出警告；半透明像素仍属于轮廓，实际颜色透明度由贴图渲染处理。

各显示场景 ​

六个启用模块都通过契约测试保持相同含义，其中 NeoForge 1.21.1 是变换基准：

  • 背包界面使用正面、全亮显示。
  • 掉落物缩放为 0.5。
  • 展示框使用 0.75。
  • 其他第三人称场景使用 0.75。
  • 第一人称左右手先应用各自镜像的平移和旋转，再使用 0.68 缩放，避免两只手方向相反时错位。

这些是 item-texture 平面物品的固定客户端变换。服务端 YAML 中的 scale、position、rotation 用于三维模型路径，不是平面贴图的分场景覆盖。

单件物品动态缩放 ​

业务插件可以通过 ChaEngineItemAPI.setCarrierItemScale 给某个 ItemStack 写入大于 0 的有限缩放倍率。该倍率与配置中的基础变换叠加，并同时作用于三维模型和平面 item-texture；不设置时倍率为 1.0。

getCarrierItemScale 读取已写入倍率，没有有效值时返回 null；clearCarrierItemScale 删除倍率并恢复 1.0。倍率保存在物品自身数据中，物品被复制或保存时会随物品保留。

跨版本一致性 ​

Forge 1.16.5、Forge 1.20.1 与 NeoForge 1.21.1、1.21.4、1.21.8、1.21.11 均使用相同的物品模型 ID、自动匹配、动态缩放、平面贴图选择和第一人称左右手变换。版本适配只处理游戏 API 差异，不改变 YAML。

常见问题 ​

物品显示成原版材质：确认它是由 ChaEngine 创建并带有物品模型 ID，而不是普通纸张。

填写 item-texture 后三维动画消失：这是预期行为；平面贴图路径不会渲染三维模型。删除 item-texture 才会使用模型和动画。

贴图轮廓有多余凸起：清理 PNG 中肉眼难见但 Alpha 不为零的像素。

物品被放置：把 material 改成不可放置物品。ChaEngine 不会把物品模型自动升级为方块模型。

自动匹配到了错误模型：检查所有可能命中的 match，并提高更具体规则的 priority。

动态缩放没有生效：倍率必须是大于 0 的有限数，并且业务代码需要修改玩家实际持有或保存的 ItemStack，不能只修改未放回背包的副本。

MythicMobs 物品仍显示原版材质：确认 ChaEngine 与 model 的缩进、ID 是否来自 item/*.yml，执行 /chaengine reload 后重新生成物品，并检查服务端是否记录了未知 ID 的一次性警告。只检查已经存在的旧物品不会触发新的绑定。

只有某一客户端版本方向异常：先确认安装的是该 Minecraft 版本对应文件，再保留相同资源和 YAML 复现；六个模块的公开变换语义应一致。

相关文档 ​