全局 Tooltip 样式 ​

ChaUI 的 Tooltip 皮肤由服务端插件数据目录中的 tooltip-styles.yml 统一管理。页面 yml 不包含 style 或 style.tooltip 节点；服务器在玩家完成协议握手后把当前完整注册表同步给客户端。

样式只替换背景、边框、内边距、换行宽度和定位。显式文本仍保留原文本，物品仍使用 Minecraft 原生富 Tooltip 内容，包括名称颜色、Lore、附魔、属性、高级信息与可用的 Mod 扩展组件。

完整示例 ​

styles:
  item_frame:
    path: gui/tooltip/item_frame.png
    gifLoop: true
    gifLoopCount: 0
    sourceX: 0
    sourceY: 0
    sourceWidth: 32
    sourceHeight: 32
    slice:
      left: 6
      right: 6
      top: 6
      bottom: 6
    render:
      left: stretch
      right: stretch
      top: tile
      bottom: tile
      center: stretch
    padding:
      left: 8
      right: 8
      top: 6
      bottom: 6
    minWidth: 32
    minHeight: 20
    maxWidth: 240
    wrap: true

rules:
  - id: rare_items
    source: item
    priority: 100
    when: 'item.count > 0 && item.loreText.contains("稀有")'
    style: item_frame
  - id: all_items
    source: item
    priority: 0
    when: 'true'
    style: item_frame
  - id: all_explicit
    source: explicit
    priority: 0
    when: 'true'
    style: item_frame

source: explicit 只匹配组件显式 tooltip，source: item 统一匹配普通物品槽、物品展示、容器绑定物品和原版背包、箱子等容器里的物品提示。两类来源互不替代，因此需要通用兜底时，应分别添加一条 when: 'true' 规则。

原版背包与箱子的背景换肤 ​

原版背包、箱子等容器无需先替换成 ChaUI 页面，也可以使用上述 all_items 规则。将图片放到客户端 resourcepacks/ChaUI/gui/tooltip/item_frame.png，按实际素材填写源图尺寸和切片，保存配置并执行 /chaui reload，再悬浮物品即可查看。

原版容器只替换背景和边框；文字、Lore、附魔、其他 Mod 的提示内容，以及换行和位置都保留原有行为。背景围绕原版内容按 padding、minWidth/minHeight 与九宫格绘制；wrap/maxWidth 只影响 ChaUI 页面中的 Tooltip。屏幕边缘没有足够空间容纳皮肤时保留原版背景。

原版容器的条件上下文为 page.mode == "native"；生存背包的 page.id 为 player_inventory，其他容器为 container。component.id/type 为空字符串，vars/vals 为空；item.* 仍来自实际悬浮物品。上面的完整配置会同时作用于 ChaUI 与原版容器；只希望原版容器命中时，将对应规则的 when 改为 page.mode == "native"。

规则顺序 ​

客户端先按 priority 从高到低排列规则，同优先级保持 tooltip-styles.yml 中的原始顺序。筛选出当前 source 后，从前向后求条件，命中第一条即停止（first match）。运行时条件求值失败只跳过该条规则；没有规则命中时显示原版 Tooltip。

条件上下文包括：

• page.id、page.mode；
• component.id、component.type；
• item.id、item.count、item.name、item.lore、item.loreText；
• 实际命中页面层的 vars 与 vals。

contains、startsWith、endsWith 属于 ChaUI Script 通用标准库，并非 Tooltip 专用函数。推荐使用对象方法，例如 item.name.contains("宝石")、item.name.startsWith("精炼") 与 item.name.endsWith("核心")；函数式兼容写法 contains(value, part) 继续可用。所有字符串判断都区分大小写，不支持正则。

item.lore 是 List<String>，适合用 item.lore.contains("完整 Lore 行") 判断完整一行，或用 item.lore[0].contains("片段") 判断指定行；实际使用索引时应先判断该行不为 null。item.loreText 是按 \n 拼接的兼容字符串。显式文本来源的 item 固定为空物品语义。

九宫格字段 ​

path 使用客户端 resourcepacks/ChaUI 下的安全相对路径，或受支持的 HTTP/HTTPS 图片。支持 PNG、JPG、JPEG 和 GIF；GIF 按文件帧延迟播放。gifLoop 默认开启，gifLoopCount 默认 0（无限循环），设置为正数时播放指定次数后停在最后一帧。GIF 的每一帧使用同一源图选区和九宫格布局。

sourceX/sourceY/sourceWidth/sourceHeight 从一张图片中选取源区域。slice.left/right/top/bottom 的单位是源纹理像素：四角保持源尺寸，边只沿一个方向变化，中心填满剩余区域。padding 的单位是 GUI 像素。minWidth/minHeight/maxWidth 控制最终外框，wrap 控制可安全拆分的文字是否换行。

render 的四条边和中心可分别使用：

• stretch：把对应区域拉伸到目标长度；
• tile：重复平铺，末尾只裁剪不足一块的部分。

某个切片值为 0 时，对应边和两个角为零尺寸且不提交片段；四边都为 0 时只绘制中心。单个 Tooltip 最多生成 1024 个九宫格片段，超过预算会整次回退原版，避免极小平铺纹理制造大量绘制调用。

回退规则 ​

本地或远程素材仍在加载、文件缺失、解码失败、源区越界、切片非法、屏幕空间不足、富组件无法无损换行或片段超过预算时，ChaUI 不绘制半套皮肤，而是直接显示完整原版 Tooltip。

当前作用域为 ChaUI 的 screen、container 和 GUI 子页面，以及原版背包、箱子等容器中的物品提示背景。HUD、world 页面和原版普通按钮提示不使用此注册表。

这套单图切片是 Tooltip 专用几何，不是矩形组件的能力；rect 仍然只绘制纯色。