猹件开发组

Appearance

On this page

物品背景 ​

物品背景会在背包、箱子等物品槽中，根据物品名称或 Lore 匹配一张 16×16 背景图。它适合表现品质框、稀有度底色、任务物品标识，不会修改物品本身，也不会替代物品模型。

准备资源 ​

背景图片放在每个客户端的 resourcepacks/ChaEngine/model/ 下。下面的配置会读取：

text
resourcepacks/ChaEngine/model/item-background/epic.png

背景支持透明 PNG 和动态 GIF。建议把主体内容控制在 16×16 物品槽范围内；图片尺寸可以大于 16×16，显示时会缩放到物品槽大小。

GIF 会按照文件中的帧延迟循环播放。同一路径的背景共享播放进度，所以同一界面里的相同品质框会保持同步；不同 GIF 从各自第一次加载时开始播放。零延迟帧按 100 毫秒显示，避免动画无间隔跳帧。

完整配置 ​

服务端文件位置：plugins/ChaEngine/item-background/*.yml

yaml
史诗品质框:                                  # 背景 ID；同名节点不要重复
  texture: "item-background/epic.png"       # 相对于客户端 model/ 的 PNG 路径
  priority: 100                              # 多个背景同时匹配时，数值大的优先
  match:                                     # 多行规则之间是“或”
    - "name#contains#史诗"                  # 名称中包含“史诗”即可匹配
    - "lore#contains#稀有度：史诗"          # 任意一行 Lore 包含该文字即可匹配

任务史诗框:
  texture: "item-background/quest-epic.png" # 另一张客户端背景图
  priority: 200                              # 比普通史诗框优先
  match:
    - "name#contains#任务,lore#contains#稀有度：史诗" # 同一行逗号分隔的条件必须同时成立

精良动态品质框:
  texture: "item-background/rare.gif"       # 相对于客户端 model/ 的动态 GIF 路径
  priority: 120                              # 高于普通精良背景时优先显示
  match:
    - "name#contains#精良"
    - "lore#contains#稀有度：精良"

字段说明 ​

字段必填默认值说明
texture是无相对于 resourcepacks/ChaEngine/model/ 的 PNG 或 GIF 路径
priority否0多个配置同时匹配时，数值较大的先使用
match是无至少包含一条有效的名称或 Lore 规则

优先级相同时，使用配置加载顺序中更靠前的背景。为了让结果稳定，重叠规则应主动设置不同的 priority，不要依赖文件枚举顺序。

匹配规则 ​

每个条件使用 字段#操作符#值：

字段读取内容
name物品当前显示名称的纯文本
lore物品 Lore 的任意一行纯文本
操作符含义
start以指定文字开头
end以指定文字结尾
equal与指定文字完全相等
notEqual与指定文字不相等
contains包含指定文字
notContains不包含指定文字
  • match 的多行之间是“或”：任意一行成立即可。
  • 同一行用英文逗号分隔时是“且”：所有条件都成立才匹配。
  • 字段、操作符和值区分大小写；未知字段、未知操作符、空值和格式不完整的整行规则不会生效。
  • lore 条件只要有一行 Lore 满足即可。

生效与重载 ​

保存配置后重载 ChaEngine，再让在线客户端接收最新配置。背景图片仍由客户端本地或 ChaAssets 提供，服务端不会发送 PNG 或 GIF 文件。

修改同一路径图片后，按资源更新流程让客户端切换到新资源代次；使用 ChaAssets 时也要更新包与授权。客户端离开服务器或资源代次改变时会清理已加载背景，重新进入后按新配置匹配。

GIF 使用建议与限制 ​

GIF 支持透明区域、局部帧以及常见的帧清理方式。为了避免物品栏一次显示多个动画时占用过多资源，建议优先制作接近 16×16 的图片，并删除肉眼看不出变化的重复帧。

  • 每个 GIF 最多 512 帧。
  • 画布宽和高都不能超过 4096 像素。
  • 画布像素数乘以帧数不能超过 16,777,216。
  • GIF 会始终循环播放；文件中设置的有限循环次数不会让物品背景永久停在最后一帧。
  • 超出限制或包含损坏帧时，整张背景不会显示，并在客户端日志记录原因。

常见问题 ​

背景完全不显示：先确认服务端成功加载该配置，再检查客户端图片是否位于 resourcepacks/ChaEngine/model/ 下的正确相对路径。

总是显示了另一个背景：比较所有可匹配配置的 priority；数值大的优先，数值相同才看加载顺序。

名称看起来一样却匹配失败：规则按纯文本且区分大小写匹配。先用 contains 缩小范围，再逐步改成 equal。

组合条件没有生效：同一条规则必须使用英文逗号连接，且每个条件都保持完整的 字段#操作符#值 格式。

物品图标被背景遮住：背景在物品图标之前绘制；检查 PNG 是否把中心区域做成了不透明内容，并改用带透明中心的边框图。

GIF 提示 Bad PNG Signature：该客户端仍在使用只支持 PNG 的旧版 ChaEngineMod。请升级与当前游戏版本对应的客户端 Mod，不要只把 GIF 文件扩展名改成 .png。

GIF 播放太快或闪烁：检查制作软件导出的帧延迟；零延迟帧会按 100 毫秒处理。也要确认动画没有超过限制或包含大量尺寸不同的局部帧。

相关文档 ​