客户端安装指南 ​

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

安装前准备 ​

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

• 使用 Minecraft 1.20.1、1.21.1、1.21.4、1.21.8、1.21.11 或 26.2。
• Minecraft 1.20.1 安装 Forge 47.4.10 至 47.4.x；Minecraft 1.21.x 与 26.2 安装对应版本的 NeoForge，1.21.11 也可以选择 Fabric。
• Minecraft 1.20.1 游戏实例使用 Java 17，Minecraft 1.21.x 使用 Java 21，Minecraft 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 中记录一次原因。

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

素材如何分发给玩家 ​

ChaUI 只读取当前客户端本地已有的素材，不会把管理员电脑中的图片、GIF 或音效自动发送给其他玩家。

正式发布页面前，请通过服务器自己的客户端、整合包或更新 Mod，将同一份 resourcepacks/ChaUI/ 素材分发给所有玩家。页面文件可以由服务端同步，但页面引用的素材文件必须提前存在于每位玩家的客户端中。

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

更新 Mod 与素材 ​

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

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

常见问题 ​

Mod 没有加载 ​

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

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

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

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

页面出现缺失图片 ​

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

GIF 没有从头播放 ​

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

音效没有播放 ​

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

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

这表示素材只存在于管理员客户端。请使用服务器自己的客户端更新方案，把相同的 resourcepacks/ChaUI/ 目录分发给所有玩家。