猹件开发组

Appearance

On this page

安全回退与排错 ​

容器替换优先保证原版菜单可用。只要 ChaUI 无法唯一且安全地建立替换会话，就会保留或恢复原版界面，不会让玩家停留在一个没有真实槽位的假菜单中。

哪些情况会回退原版 ​

  • 没有页面匹配当前目标、标题或行数；
  • 两个页面比较后仍处于相同最高优先级；
  • 服务端确认玩家当前真实容器与客户端候选不一致；
  • ChaUI 与 ChaUIMod 协议版本不兼容；
  • 页面配置无法解析或未通过校验；
  • 替换运行时发生阻止继续安全交互的关键错误。

单张图片缺失只使用普通缺失素材策略，不会因为一个装饰素材不存在就放弃整个替换页面。

打开后仍是原版界面 ​

按顺序检查：

  1. 页面 display.mode 是否为 container。
  2. target 是否与当前界面一致：生存背包用 player_inventory，通用箱子用 chest。
  3. 箱子标题是否在去掉颜色后仍符合 exact、prefix 或 contains。
  4. rows 是否包含当前顶部箱子的真实行数。
  5. 是否有另一张页面使用同样的最高优先级和匹配精度。
  6. 客户端是否安装与服务端协议一致的 ChaUIMod。

双箱子通常是 6 行，单箱子通常是 3 行。许多插件菜单虽然看起来没有填满，顶部容器仍可能是 6 行，应以真实容器行数为准。

日志提示匹配冲突 ​

冲突不是随机选择失败，而是两张页面同样适合当前容器。处理方式任选一种：

  • 给更具体的页面提高 priority；
  • 把 any 改成 exact、prefix 或 contains；
  • 为已知菜单填写 rows；
  • 删除或改名不再使用的重复页面。

修改后重新加载页面配置，再次打开容器验证。

页面打开了，但按钮点错格 ​

确认 containerBinding 从 0 开始。插件所说“第 14 格”通常对应 container_13。还要确认按钮没有被更高 z 的 pointerEvents: block 组件遮挡。

绑定按钮必须保持：

yaml
visible: true
enabled: true
pointerEvents: auto
containerBinding: container_13

若 Press 脚本会动态改绑，本次 Click 仍使用按下时捕获的旧槽位，新绑定在下一次点击生效。

名称或 Lore 没有刷新 ​

ChaUI 显示的是原版容器同步后的物品状态。第三方插件处理点击后若替换了菜单物品，等待原版同步到达，名称、Lore、图标和提示会一起刷新。

检查响应式路径是否使用了正确组件 ID：

text
{vals.container.components.menu_button.name}
{vals.container.components.menu_button.loreText}

若组件已通过脚本解除绑定，对应信息会变为空槽值。

item_slot 无法拖拽 ​

需要完整原版交互时使用绑定的 item_slot，并确认组件启用、参与命中且没有被其他组件遮挡。item_display 只负责展示，button 只代理按钮式槽位点击，二者不会提供完整拖拽操作。

reload 后发生了什么 ​

ChaUI reload 不会强行关闭第三方插件容器。当前替换页面会执行一次旧配置的关闭生命周期并释放资源，然后在同一个原版容器上重新匹配：

  • 新配置仍匹配：打开新的替换页面；
  • 新配置不再匹配：直接显示原版界面；
  • 新配置发生冲突或无效：安全回退原版。

若要验证标题或行数变化，最稳妥的方法仍是关闭并重新打开测试容器。

上线前检查清单 ​

  • 每个重要插件菜单都有明确标题与行数规则。
  • 通用 any 页面使用较低优先级。
  • 没有两张玩家背包页面处于相同最高优先级。
  • 每个交互按钮都实际点击了第三方插件预期槽位。
  • 名称、Lore 和原版 tooltip 在物品变化后能刷新。
  • Shift、拖拽、数字键等需求使用 item_slot 测试。
  • 缺失素材、配置冲突和协议不一致时都能看到原版界面。