客户端安装指南 ​

ChaUIMod 是 ChaUI 的客户端部分，负责显示页面、运行可视化编辑器，并读取当前客户端中的图片、GIF 与音效素材。每位需要查看 ChaUI 页面或使用编辑器的玩家，都需要安装与游戏版本对应的客户端 Mod。

使用自定义铭牌并调用玩家名称显隐 API 时，服务端与玩家客户端都需要更新到支持此功能的配套包。若铭牌已经显示但仍叠着原版名字，先核对客户端是否也已更新，并完整退出游戏后替换 Mod 再启动；仅重载服务端页面不能更新客户端功能。

安装前准备 ​

安装前请确认客户端满足以下条件：

• 使用 Minecraft 1.16.5、1.20.1、1.21.1、1.21.4、1.21.8、1.21.10、1.21.11、26.1.2 或 26.2。
• Minecraft 1.16.5 安装 Forge 36.2.42；Minecraft 1.20.1 可以安装 Forge 47.4.10 至 47.4.x 或 Fabric；Minecraft 1.21.1、1.21.4 与 1.21.11 可以安装对应版本的 NeoForge 或 Fabric，1.21.8 与 1.21.10 使用 NeoForge，26.1.2 使用 Fabric，26.2 使用 NeoForge。
• Minecraft 1.16.5 Forge 游戏实例使用 Java 11，Minecraft 1.20.1 使用 Java 17，Minecraft 1.21.x 使用 Java 21，Minecraft 26.1.2 与 26.2 使用 Java 25。
• 已准备与当前 Minecraft 版本对应的 ChaUIMod 文件。
• 目标服务器已经安装 ChaCore 与 ChaUI 服务端插件。

安装客户端 Mod ​

1. 完全退出游戏和启动器中的运行实例。
2. 打开当前 Minecraft 实例使用的游戏版本目录。
3. 找到其中的 mods/ 目录；如果启动器尚未创建，可以手动建立。
4. 将对应版本的 ChaUIMod 文件放入 mods/。
5. 通过与文件对应的 Forge、NeoForge 或 Fabric 启动游戏。

当前游戏版本目录/
└─ mods/
   └─ ChaUIMod.jar

不同启动器对“游戏版本目录”的命名和位置可能不同。多实例启动器通常会为每个整合包或版本建立独立目录，请以当前实例实际使用的目录为准，不要误放到另一个版本的 mods/ 中。

连接服务器并验证 ​

启动游戏后，可以在 Mod 列表中确认 ChaUI 已加载。进入安装了 ChaUI 服务端插件的服务器，再由管理员打开一个示例页面或编辑器进行验证。

满足以下情况即可认为双端安装正常：

• 客户端能够正常进入服务器，没有出现 Mod 或通信版本不匹配提示。
• 服务器打开页面后，客户端能看到 ChaUI 页面。
• 具备编辑权限的管理员能够进入游戏内编辑器。
• 页面按钮、输入框等基础交互能够正常响应。

如果页面能够打开但图片显示为缺失素材，请继续配置本地资源目录。

创建 ChaUI 素材目录 ​

图片与音效统一放在当前游戏版本目录的 resourcepacks/ChaUI/ 下。这个位置是 ChaUI 读取本地素材的固定根目录。

推荐结构如下：

当前游戏版本目录/
├─ mods/
│  └─ ChaUIMod.jar
└─ resourcepacks/
   └─ ChaUI/
      ├─ gui/
      │  ├─ logo.png
      │  ├─ button.jpg
      │  ├─ background.jpeg
      │  └─ animation/
      │     └─ loading.gif
      └─ sounds/
         ├─ click.ogg
         └─ ui/
            └─ open.ogg

gui/ 和 sounds/ 是推荐分类，不限制继续建立子目录。只要页面中填写的相对路径与实际文件位置完全一致，ChaUI 就可以找到对应素材。

支持的资源格式 ​

文件扩展名建议统一使用小写，避免不同系统对文件名大小写处理不同而造成素材缺失。

页面路径应该怎样填写 ​

页面配置和编辑器中填写的是相对于 resourcepacks/ChaUI/ 的路径，不需要写出前面的游戏目录。

路径必须满足以下规则：

• 使用 / 分隔目录，不使用反斜杠。
• 只能填写相对于 resourcepacks/ChaUI/ 的路径，不能填写磁盘绝对路径。
• 不能使用 ../ 等方式跳出 ChaUI 素材目录。
• 路径不能为空，也不要包含空白字符或控制字符。
• 文件名、扩展名和大小写需要与实际文件保持一致。

自定义客户端窗口标题与图标 ​

游戏主窗口的大小可以由服务器统一限制：固定尺寸模式只能选择服务器预设，固定比例模式可以拖动大小，视频设置只需调整宽度。全屏时多余区域显示黑边。最后收到的合法限制会在断线和重启后保留，取消方式见窗口尺寸与比例。外置编辑器窗口不受该限制影响。

ChaUIMod 首次启动后会在当前游戏版本目录生成 config/chaui-client.json：

{
  "windowTitle": "",
  "windowIcon": ""
}

• windowTitle 填写客户端窗口顶部标题，留空时保持原版标题。填写非空标题后，即使进入多人游戏、连接服务器或切换其他原版界面，ChaUIMod 也会恢复这条自定义标题。
• windowIcon 填写相对于 resourcepacks/ChaUI/ 的图片路径，例如 gui/window.png；支持 PNG、JPG、JPEG 与 GIF，GIF 只取第一帧作为静态窗口图标。
• 图标路径使用与页面图片完全相同的安全相对路径规则，也可以由 ChaAssets 提供。路径非法、素材缺失或图片损坏时保留原版图标，并在 latest.log 中记录一次原因。

修改后需要完全重启客户端。配置文件只在启动时读取一次，窗口图标也只在启动时加载一次；运行期间持续保持标题不会重复读取配置或重新解码图标。该配置只作用于本机，不会由服务器同步给其他玩家。

素材如何分发给玩家 ​

普通页面仍只读取当前客户端本地已有的素材，不会把管理员电脑中的图片、GIF 或音效自动发送给其他玩家。正式发布普通页面前，请通过服务器自己的客户端、整合包或更新 Mod，把同一份 resourcepacks/ChaUI/ 素材分发给所有玩家。

原版菜单替换页可以由服主把需要同步的小型素材放入服务端 plugins/ChaUI/vanilla-menu-assets/**。这些文件会随原版菜单页面包发送，目录结构与客户端 resourcepacks/ChaUI/ 相同；运行时先读取当前活动包，缺失时再尝试 ChaAssets 和客户端本地目录。游戏内编辑器只保存页面 yml，不会自动上传管理员电脑中的素材。完整限制和预置包方式见页面包与素材。

如果某位玩家仍缺少素材，ChaUI 会按缺失素材处理；这不会影响服务端保存的页面，但该玩家看到的页面可能缺少图片、动画或音效。

更新 Mod 与素材 ​

更新 ChaUIMod 时，请先完全退出游戏，再替换当前实例 mods/ 中的旧文件。不要同时保留多个 ChaUIMod 文件，避免重复加载或版本冲突。

更新素材时，可以直接覆盖 resourcepacks/ChaUI/ 下的对应文件。若文件路径发生变化，还需要在编辑器中更新页面引用并重新保存。为了避免部分玩家仍使用旧素材，建议让客户端更新工具按同一版本统一分发。

常见问题 ​

Mod 没有加载 ​

确认文件放在当前实例实际使用的 mods/ 中，并检查 Minecraft、加载器、Java 与 ChaUIMod 是否属于同一目标版本。Forge 1.16.5 请使用 36.2.42 和 Java 11；Forge 1.20.1 请确认 Forge 不低于 47.4.10，且没有误装 Fabric 或其他版本的 ChaUIMod。

Minecraft 26.2 还应确认实例使用 Java 25，并选择了 OpenGL 图形后端。Vulkan 下 ChaUI 会安全停止接管界面，不会用不完整页面替换原版界面。

NeoForge 提示 SnakeYAML 版本冲突 ​

如果启动页写着 org.yaml:snakeyaml 存在冲突，并同时列出 ChaUI 与其他 Mod，请先替换当前实例中的旧 ChaUIMod，使用对应 Minecraft 版本的新配套文件。新版允许 SnakeYAML 2.2 及以上、3.0 以下的版本，避免旧版固定要求 2.2 时与要求 2.6 的 Mod 冲突。

不要只更新服务端插件，也不要手动向 mods/ 塞入 SnakeYAML 库文件。替换后完全重启游戏，若仍有冲突，把启动页列出的双方版本范围和 latest.log 一起保留。其他 Mod 提示缺少自己的前置时，按它们各自对应的 Minecraft 与加载器版本补齐；这类缺失不会因修复 ChaUI 依赖范围而自动安装。

能进入服务器，但页面没有打开 ​

先确认服务端已经正常安装 ChaUI，并由管理员触发了页面打开操作。如果其他玩家可以打开，再检查当前客户端的 Mod 是否加载成功以及双端版本是否一致。

计时器读取的鼠标位置不变，或松手后脚本仍认为按着 ​

先确认回调正文直接读取 vals.mouse.x/y、vals.mouse.leftDown 等字段，没有只读取启动时保存到 vars.* 的旧值。可以用鼠标状态检查脚本观察移动和松手后的输出。

旧客户端的定时和延时脚本可能沿用任务创建时的鼠标状态。请更新对应 Minecraft 和加载器的 ChaUIMod，并完全重启游戏；仅更新服务端插件或执行 reload 无法修正客户端脚本执行。内置 dragMode 使用实时鼠标交互，不受这项旧快照问题影响。

页面出现缺失图片 ​

检查文件是否位于当前实例的 resourcepacks/ChaUI/ 下，再逐字核对页面相对路径、文件扩展名和大小写。不要把素材只放进启动器的公共目录或另一个游戏实例中。

HUD 文字没有替换成图标 ​

如果实体名牌中的同一标记已经显示图标，但 ChaUI HUD 文字仍显示 [BOSS] 等原字符串，请核对客户端文件。Forge 1.16.5、Forge/Fabric 1.20.1 与 NeoForge/Fabric 1.21.1 的旧客户端存在此问题，需要更新为包含此修复、与游戏版本和加载器对应的 ChaUIMod，并完全退出游戏后重新启动。仅执行 /chaui reload 不会更新客户端 Mod。

文字组件需使用原版字体；自定义 TTF 不参与全局文字图标替换。规则与素材的检查方法见全局文字图标。

自定义字体缩放后字距或上下位置不齐 ​

自定义 TTF 可以使用 textSize: 1.2 等小数字号，不需要强制改成整数。旧客户端在小数字号下可能出现字距不均或字形高低不齐，需要安装包含 TTF 小数缩放修复的配套 ChaUIMod，并完全重启游戏；提高 fontResolution 或仅执行服务端 reload 不能解决这项客户端绘制问题。

如果只在鼠标悬浮时变化，请核对常态和悬浮文字的字体、字号、分辨率及阴影设置是否一致。没有填写 fontResolution 的组件使用默认值 32，不会继承另一个组件的设置。配置说明见自定义字体与颜色。

GIF 没有从头播放 ​

每次重新打开页面，GIF 都会从第一帧开始。若运行中替换了组件图片路径，也会重新开始播放。请确认页面实际引用的是目标 GIF 文件。

音效没有播放 ​

确认文件为 OGG 格式，且位于 resourcepacks/ChaUI/ 内。页面中应填写类似 sounds/click.ogg 的相对路径，不能使用 MP3、绝对路径或反斜杠。

管理员能看到素材，其他玩家看不到 ​

普通页面出现这种情况，说明素材只存在于管理员客户端。请使用服务器自己的客户端更新方案，把相同的 resourcepacks/ChaUI/ 目录分发给所有玩家。原版菜单替换页则可以把适合网络同步的小型素材加入 vanilla-menu-assets/**，执行 /chaui reload 后再检查页面包是否发布成功。