物品模型 ​

物品模型用于制作不可放置的自定义物品。服务端可以把物品模型 ID 写入物品自身 NBT；没有模型 ID 的普通物品，也可以按材质、名称或 Lore 自动匹配。客户端根据配置选择平面贴图或三维模型渲染。

完整配置 ​

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

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]                      # 三维模型旋转角度

字段说明 ​

model、texture、animation 和 item-texture 均支持本地相对路径或 HTTP/HTTPS 直链，可以混用。完整网络配置、下载缓存与失败重试见网络资源。

配置至少要有一条可用渲染路径：item-texture，或者有效的三维 model 与所需纹理。BBModel 使用工程内嵌或引用纹理时，texture 可以留空；网络 BBModel 直链也遵循这一规则。不要为不存在的公开字段编写分场景变换。

运行规则 ​

基础材质与放置行为 ​

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

模型 ID 与自动匹配 ​

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

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

材质值可以写 minecraft:paper、paper 或 PAPER，三者都表示原版纸；材质值不区分大小写，省略命名空间时使用 minecraft:。模组物品请填写完整 ID，例如 examplemod:letter。这里匹配的是物品类型，不是贴图文件或显示名称，也不会把同名的其他物品当作纸。

name 和 lore 会同时清理实际文本和规则值中的颜色与格式代码，支持 §a、&a、展开式 RGB 和 &#RRGGBB / §#RRGGBB。例如名称 §6青铜护符 与规则 name#equal#&a青铜护符 可以匹配；Lore 中间插入颜色代码也不会打断文字比较。只有颜色代码的规则值无效，普通文字、空格和大小写仍参与比较。匹配过程不会修改物品显示效果；权限 perm 仅用于实体模型。

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

让所有纸使用同一个模型 ​

在 plugins/ChaEngine/item/paper-model.yml 中放入以下完整配置，并准备对应的客户端模型和贴图资源：

paper_model:                               # 物品模型 ID
  display: "模型纸张"                     # 仅影响通过 get/give 新生成的物品名称
  material: "minecraft:paper"             # get/give 使用的载体；此字段本身不负责匹配
  model: "paper/paper.geo.json"           # 客户端 model/ 下的三维模型
  texture: "paper/paper.png"              # 模型贴图
  animation: ""                           # 本例不使用动画
  default-animation: ""                   # 无默认动画
  item-texture: ""                        # 留空以显示三维模型
  match:
    - "material#equal#minecraft:paper"    # 所有未绑定模型 ID 的纸均匹配
  priority: 50                             # 多个自动匹配模型重叠时使用较大值
  scale: 1.0                               # 模型缩放
  position: [0, 0, 0]                     # 位置偏移
  rotation: [0, 0, 0]                     # 旋转角度

同时更新服务端插件与对应版本的客户端 Mod，保存配置后执行 /chaengine reload。普通纸、改过名的纸和带 Lore 的纸都会使用这个模型；已有物品模型 ID 的物品仍优先使用绑定模型。自动匹配只改变显示，不会修改原物品的材质、名称、Lore 或 NBT。

如果只想匹配名称为“信纸”的纸，可以把该行改为 material#equal#PAPER,name#equal#信纸。要排除纸则使用 material#notEqual#PAPER；材质不支持 contains 等文字操作符，也不能省略中间的操作符。

直接绑定 MythicMobs 物品 ​

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

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

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

辅助命令 ​

/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。

常见问题 ​

物品显示成原版材质：确认它带有有效的物品模型 ID，或能命中至少一条 match。只填写顶层 material: "minecraft:paper" 不会自动替换普通纸，仍需配置 material#equal#minecraft:paper 匹配规则，并更新两端程序、重载配置。

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

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

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

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

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

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

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

相关文档 ​

• 第一个物品模型
• 模型动画
• 物品背景
• 资源目录
• 命令参考
• Java API