全局文字图标 ​

全局文字图标可以把指定字符串显示成图片。例如，服务器仍然发送 §金币，玩家看到的却是一枚金币图标。原始聊天内容、物品名称和 Lore 不会被改写，因此复制文字、插件判断和物品数据仍保持原样。

规则写在服务端 plugins/ChaUI/font-icons.yml。path 可以填写当前游戏目录 resourcepacks/ChaUI 下的本地图片路径，也可以填写 http:// 或 https:// 图片 URL。网络图片由客户端异步下载并按完整 URL 缓存，不会阻塞游戏渲染；下载失败时保留原文字。

准备素材 ​

先在玩家客户端准备下面的文件：

resourcepacks/ChaUI/
└─ icons/
   ├─ coin.gif
   └─ vip.png

当前支持 PNG、JPG、JPEG 和 GIF。文件名与目录名区分大小写时，应保证配置与实际路径完全一致。

一份可以直接使用的完整配置 ​

# plugins/ChaUI/font-icons.yml
"§金币":
  # 客户端 resourcepacks/ChaUI 下的相对路径
  path: "icons/coin.gif"
  # 不写时均为 9；范围 1 至 256
  width: 11
  height: 11

"[VIP]":
  # 静态图片同样放在客户端 resourcepacks/ChaUI 下
  path: "icons/vip.png"
  # width 也是图标在文字排版中占用的宽度
  width: 18
  # height 只控制绘制高度
  height: 9

保存文件后执行 /chaui reload。重载成功后，新规则会直接用于当前在线玩家后续显示的文字。

一份配置最多包含 256 条规则，全部规则的有效配置内容合计不能超过 1 MiB。

哪些文字会生效 ​

只要文字经过 Minecraft 原版字体显示，就会使用同一套替换规则，常见位置包括：

• 聊天消息；
• 物品名称、Lore 和 Tooltip；
• 原版 GUI 中的文字；
• 实体名牌；
• 使用原版字体的 ChaUI 文字与按钮文字。

ChaUI 自定义 TTF 字体和其他 Mod 自己实现的独立字体渲染器不在当前范围内。同一段文字只改变显示结果，不会改变服务器发送的字符串或物品数据。

重叠规则与最长匹配 ​

多条规则从同一位置都能匹配时，ChaUI 始终选择更长的完整字符串。例如同时配置 [V] 和 [VIP]，文字中出现 [VIP] 时会显示 [VIP] 对应的图标，不会先替换成 [V]。

匹配按完整 Unicode 字符处理，中文和常见扩展字符都可以直接放在顶层键中。建议把具有业务含义的标记写得明确，避免普通聊天内容意外命中。

GIF 播放 ​

GIF 按文件中每一帧自带的停留时间播放，并自动循环。同一个 path 在聊天、Tooltip 或其他位置同时出现时，会共享相同播放进度，因此画面保持同步。

重新加载配置时，如果规则仍使用同一路径，现有动画会继续播放；规则不再使用该路径后，对应资源会被释放。GIF 不需要额外配置循环次数或播放速度。

缺失素材与安全回退 ​

图片还在读取、文件不存在、路径错误或图片损坏时，ChaUI 会显示被匹配的完整原字符串，并使用原字符串本来的宽度参与排版。例如 §金币 的图片缺失时，玩家仍会看到完整的 §金币，不会留下空白，也不会只显示其中一部分。

/chaui reload 会先检查整份候选配置：

• 重载配置非法时，继续使用重载前最后一份有效规则；
• 首次启动时配置非法，ChaUI 会以空规则继续启用，所有文字保持原样；
• 修正配置并再次成功重载后，新规则才会整体生效。

当前不支持的能力 ​

第一版不支持网络图片、服务端上传或分发素材、绘制偏移、源图裁剪、染色、独立占用宽度、GIF 循环次数、Java API、图形编辑器或脚本动态修改。需要调整显示大小时，请使用 width 和 height；需要更新图片时，直接替换客户端本地素材。

常见错误 ​