全局 Tooltip 样式 ​

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

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

完整示例 ​

styles:
  item_frame:
    path: gui/tooltip/item_frame.png
    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' 规则。

规则顺序 ​

客户端先按 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 静态图片。Tooltip 第一版只接受 PNG/JPG/JPEG，GIF 会拒绝并回退原版。

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

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

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

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

回退规则 ​

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

当前作用域仅为 ChaUI 的 screen、container 和 GUI 子页面。HUD、world 页面和 ChaUI 之外的原版界面不使用此注册表。

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