全局文字图标 ​

全局文字图标可以把指定字符串显示成图片。例如，服务器仍然发送 §金币，玩家看到的却是一枚金币图标。原始聊天内容、物品名称和 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
  # 正数向右、负数向左，支持小数；不写时为 0
  offsetX: -2.5
  # 从默认底部对齐位置向下移动 0.5；负数向上，不写时为 0
  offsetY: 0.5

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

替换规则不设条数上限，超过 256 条也可以使用。全部规则的有效配置内容合计仍不能超过 1 MiB，这里计算的是规则内容，不包含图片文件大小。每条匹配文字的长度、图片尺寸与偏移仍需符合上表范围。

调整图标的上下和左右位置 ​

height 决定图片有多高，offsetY 调整它的上下位置。保持 height 不变，将 offsetY 增加 1，图标就向下移动 1 个 GUI 像素；减少 1 则向上移动 1 个 GUI 像素。省略 offsetY 或设为 0 时，图片底部仍对齐文字基线，与以前未设置偏移的配置效果一致。

offsetX 控制左右位置：-2.5 向左移动 2.5 个 GUI 像素，1.25 向右移动 1.25 个 GUI 像素。两个偏移字段都接受小数，width 和 height 仍使用整数。小数参与实际绘制，最终视觉精细度取决于 GUI 缩放和屏幕像素。

旧字段 ascent 已替换为 offsetY，不能只改字段名并保留原数值。需要保持原显示位置时，先计算 offsetY = height - ascent，再把计算结果写入配置。例如原来 height: 9、ascent: 8.5，现在应写 height: 9、offsetY: 0.5，并删除 ascent。

例如，想在箱子标题中显示一张较大的背景图，可以使用下面的完整配置，并让箱子标题包含 [菜单背景]：

# plugins/ChaUI/font-icons.yml
"[菜单背景]":
  # 客户端 resourcepacks/ChaUI/gui/chest.png
  path: "gui/chest.png"
  width: 176
  height: 166
  # 图片向左移动 8.5 个 GUI 像素
  offsetX: -8.5
  # 从底部对齐位置向下移动 151，图片顶部比标题文字起点高 6
  offsetY: 151

此时图片按 176 × 166 显示。offsetY: 151 将图片从默认底部对齐位置下移，使图片顶部比标题文字的绘制起点高 6 个 GUI 像素。先调整到大致位置，再增减 offsetY 微调即可；实际数值取决于标题位置和素材中的透明留白。

offsetX 和 offsetY 只移动图片，不改变文字占用宽度或原版界面的绘制顺序。如果要完整替换箱子界面的布局与交互，请使用替换界面教程。服务端插件和玩家客户端 Mod 都需要配套更新后才能使用小数偏移；使用代理服时同时更新 ChaUIBC。

哪些文字会生效 ​

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

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

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

重叠规则与最长匹配 ​

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

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

GIF 播放 ​

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

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

缺失素材与安全回退 ​

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

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

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

当前不支持的能力 ​

当前不支持服务端上传或分发素材、源图裁剪、染色、独立占用宽度、GIF 循环次数、Java API、图形编辑器或脚本动态修改。调整显示大小使用 width 和 height，调整纵向位置使用 offsetY，调整横向位置使用 offsetX；本地图片更新后，替换客户端对应素材。

常见错误 ​