猹件开发组服务端安装指南
ChaUI 的服务端部分负责管理页面、保存编辑器内容、打开或关闭页面，以及处理需要由服务器确认的交互。大部分目录和文件都会在插件首次正常启动后自动生成，安装时不需要提前手工创建。
安装前准备
安装前请确认服务器满足以下条件：
- 使用 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。 - 服务端为对应版本的 Spigot 或 Paper；其他服务端核心请先确认兼容情况。
- Minecraft
1.16.5与1.20.1服务端使用 Java 17，Minecraft1.21.x使用 Java 21，Minecraft26.1.2与26.2使用 Java 25。 - 已安装与当前服务器环境匹配的 ChaCore。
- 已准备
ChaUI-2.0.4.jar；所有正式支持的服务端版本共用这一个插件文件。
双端版本需要对应
ChaUI 需要服务端插件和玩家客户端 Mod 配合使用。服务端与客户端的 Minecraft 版本必须一致，例如 1.16.5 服务端应搭配 Forge 1.16.5 客户端，1.20.1 服务端应搭配 Forge 或 Fabric 1.20.1 客户端，1.21.1 服务端应搭配 NeoForge 或 Fabric 1.21.1 客户端，26.2 服务端应搭配 NeoForge 26.2 客户端。
同时安装配套的服务端插件与客户端 Mod；当前服务端 ChaUI 与客户端 ChaUIMod 均为 2.0.4 / 协议 25。旧协议客户端不能通过只更新服务端插件来恢复使用。同版本号的早期构建也可能缺少后续新增的 API，请以随包交付记录为准。
安装插件
- 完全关闭服务器。
- 将 ChaCore 与 ChaUI 的插件文件放入服务器的
plugins/目录。 - 启动服务器并等待插件加载完成。
- 查看控制台，确认 ChaCore 与 ChaUI 均已正常启用，且没有缺少前置或 Java 版本错误。
安装前的目录大致如下：
服务器目录/
└─ plugins/
├─ ChaCore.jar
└─ ChaUI.jar实际文件名可能带有版本号，只要确认放入的是与当前服务端匹配的正式文件即可。
首次启动会自动完成什么
ChaUI 首次正常启动后，会在 plugins/ChaUI/ 下准备运行所需的默认文件。启动时只有 plugins/ChaUI/pages/ 整个文件夹不存在，才会一次性创建文件夹并释放三个内置示例页面。正常安装无需提前手工创建这些文件。
如果 pages/ 已存在，即使它是空文件夹，也不会补放示例。删除其中某个示例后，重启或 /chaui reload 都不会把它重新生成。确实需要重新取得整套示例时，先停服并将现有 pages/ 文件夹移到插件目录之外备份，再启动服务器；请保留自己的页面备份，按需恢复其中的页面。
config.yml 已提供适合直接使用的默认设置，大多数服务器无需修改。之后通过游戏内编辑器创建并保存页面时，ChaUI 也会负责生成对应的页面文件；覆盖已有页面前，旧文件会自动进入备份目录。
要求客户端模组
如果希望服务器只允许安装 ChaUIMod 的玩家进入，可以在 plugins/ChaUI/config.yml 打开客户端要求：
client-requirement:
require-mod: true # true：未完成 ChaUIMod 就绪确认的玩家会被移出服务器
ready-timeout-ticks: 100 # 等待时间，20 tick 约等于 1 秒，允许 20~600默认值为 false。打开后，玩家进入服务器时会先等待客户端就绪确认；没有安装 ChaUIMod、协议不匹配或握手格式无效时，会收到对应中文原因并被移出。修改配置后执行 /chaui reload 即可让在线玩家重新按新设置检查，不需要新增网络通道。
开箱即用
完成插件与客户端 Mod 安装后，就可以直接使用游戏内编辑器开始制作页面。除非你明确需要调整文件位置或提示文字，否则通常不需要手动改动服务端配置。
安装后的目录结构
首次启动并完成一次页面保存后，常见结构如下：
服务器目录/
└─ plugins/
├─ ChaCore.jar
├─ ChaUI.jar
└─ ChaUI/
├─ config.yml
├─ lang.yml
├─ global-scripts.yml
├─ vanilla-menu-assets/
├─ pages/
│ ├─ hud_health_demo.yml
│ ├─ chaui_feature_layout_demo.yml
│ ├─ first_chest_replacement.yml
│ ├─ 你的页面.yml
│ └─ 菜单/
│ └─ shop.yml
└─ backups/
└─ pages/
└─ 页面ID-保存时间.yml备份目录会在需要保存旧页面备份时出现。如果服务器刚安装、还没有覆盖保存过页面，看不到该目录属于正常情况。
用子目录整理页面
pages/ 支持子目录，最大深度 16。它适合把商店、副本、HUD 等页面分类收纳。子目录只用于整理文件，不会成为页面 ID 的一部分。例如 pages/菜单/shop.yml 的页面 ID 仍然是 shop，打开时不要填写 菜单/shop。
使用时请遵守以下规则：
- yml 文件名必须与根级
id完全相同，例如shop.yml对应id: shop。 - 页面 ID 在整棵
pages/目录中全局唯一。如果两个不同子目录声明了同一 ID，这个 ID 对应的冲突文件会全部拒绝加载。 - 编辑器再次保存已有页面时，会写回原位置；备份也会保留相同目录结构。
- 新建页面默认保存到
pages/根目录，之后可在服务器关闭时手动移入子目录。 - 为避免读取到目录外的文件，符号链接文件和符号链接目录会被跳过。
第三方插件如果想自带页面，请使用页面注册 API，不要直接写入 ChaUI 的数据目录。
文件与目录介绍
| 文件或目录 | 用途 | 是否需要手动处理 |
|---|---|---|
config.yml | 保存数据库、页面目录、打开提示和可选客户端要求，见完整基础配置。 | 默认不启用数据库和 ChaUIMod 强制要求；按需配置后执行 /chaui reload。 |
lang.yml | 保存插件在服务端显示的提示文字。 | 仅在需要调整提示文案时修改。 |
global-scripts.yml | 保存全局变量、服务端通用方法和 Cron。 | 首次启动自动生成；修改后执行 /chaui reload，同名同类型全局变量保留运行值。 |
vanilla-menu-assets/ | 保存需要随原版菜单页面包同步的素材，内部路径与客户端 resourcepacks/ChaUI/ 一致。 | 按需手动创建和放入；修改后执行 /chaui reload。 |
pages/ | 存放服务器可使用的页面文件。 | 由内置示例和游戏内编辑器自动产生，也可以用于迁移已有页面。 |
pages/hud_health_demo.yml | 内置 HUD 示例，用于了解状态栏页面效果。 | 仅在整个 pages/ 目录不存在时生成。 |
pages/chaui_feature_layout_demo.yml | 内置综合示例，用于查看常用组件、事件和布局效果。 | 仅在整个 pages/ 目录不存在时生成。 |
pages/first_chest_replacement.yml | 内置三行箱子替换示例，用于完成第一个原版容器替换。 | 仅在整个 pages/ 目录不存在时生成。 |
backups/pages/ | 保存页面被覆盖前的旧版本，便于误操作后找回。 | 自动生成和维护。 |
普通页面使用的图片与音效仍属于客户端本地素材，应按照客户端安装指南放入每位玩家的 ChaUI 资源目录。原版菜单页面可以把需要随页面包发送的小型素材放进服务端 vanilla-menu-assets/**；完整发布规则、大小限制和本地回退顺序见页面包与素材。
如何确认安装成功
可以按以下顺序检查：
- 控制台中 ChaCore 与 ChaUI 均显示为正常启用。
plugins/ChaUI/已自动出现。- 全新安装且没有预先创建
pages/时，其中可以看到三个内置示例页面；沿用已有目录时，以自己的页面为准。 - 安装客户端 Mod 的管理员进入服务器后，可以正常打开 ChaUI 编辑器或示例页面。
- 保存一个测试页面后，
pages/中出现对应的 yml 文件。
如果前三项正常，但客户端无法打开页面，请继续检查客户端 Minecraft 版本、加载器和 ChaUIMod 是否与服务端对应。Forge 1.16.5 使用 36.2.42，Forge 1.20.1 使用 47.4.10 至 47.4.x；1.21.x 请使用对应版本的 NeoForge 或文档中标为支持的 Fabric 版本；26.2 客户端还必须选择 OpenGL 图形后端。
更新 ChaUI
更新前建议先停止服务器，并备份整个 plugins/ChaUI/ 目录。随后替换 plugins/ 中的 ChaUI 插件文件并重新启动服务器。
不要删除 pages/，其中包含已经制作的页面。一般也不需要删除 config.yml 或 lang.yml；如果新版本需要新增默认内容，插件会按其更新方式处理。
服务端插件与客户端 Mod 必须使用兼容的同一协议，推荐一起更换为同一批配套发布文件。更换 Mod 后完全重启游戏，再重新进入服务器；/chaui reload 不会更新正在运行的插件或客户端 Mod。代理服还需同步使用支持当前协议的 ChaUIBC，详见版本兼容性。
常见问题
编辑器提示未就绪或 not_ready
玩家进入世界后，ChaUI 需要先完成客户端与服务端的就绪确认，才能打开编辑器。新版会显示具体中文原因；旧版本的 not_ready 只说明这一步未完成，不能仅凭它判断是页面损坏。
| 提示或日志内容 | 含义 | 处理方式 |
|---|---|---|
| 协议不匹配，客户端为某值、服务端要求某值 | 双端安装的 ChaUI 不配套 | 核对当前游戏实例的 mods/ 和服务端 plugins/，替换成同一批配套文件，移出旧 Jar，重启双端后重新连接。当前协议是 25。 |
| 尚未收到就绪握手 | 服务端尚未收到本次连接的客户端就绪消息 | 等待世界加载完成后重试；持续失败时检查 ChaUIMod 是否正常加载，再重新进入服务器。经过代理切服时，也检查 ChaUIBC 是否正常启用。 |
| 格式无效的就绪握手 | 收到的消息无法正常读取 | 检查是否混用了插件或 Mod 文件，查看服务端同一时间包含 client_ready 的错误。 |
| 等待玩家持久槽数据加载 | 客户端已发消息，服务端仍在读取玩家数据 | 稍后重试；持续出现时查看服务端持久槽或数据库错误。 |
| 正在完成就绪初始化 | 服务端初始化尚未结束 | 稍后再次打开；持续出现时检查服务端初始化日志。 |
| 就绪初始化失败 | 初始化过程中发生异常 | 管理员查看同一时间“客户端就绪初始化失败”的完整异常，按具体原因处理。 |
仅看到旧提示 not_ready 时，请同时提供客户端当前实例的 logs/latest.log 和服务端同一时段日志，并注明 Minecraft、加载器及双端 ChaUI 版本。日志里的协议不匹配必须先修正，删除页面或反复 reload 无法解决版本不一致。
新版客户端在收到服务端明确的未就绪拒绝后，允许重新发送就绪消息；可以稍后再次打开编辑器。这次重试不会清空已有编辑草稿，也不会绕过服务端检查。是否打开成功，仍以具体提示和服务端就绪结果为准。
页面运行异常应该看哪里
客户端在已建立的页面会话中报告运行异常时，服务端控制台会记录玩家、配置文件、页面 ID、组件、发生阶段、错误类型和原因。拥有 chaui.runtimeerrors 权限的在线管理员也会收到提示，默认 OP 拥有此权限；语言文本位于 lang.yml 的 runtime-page-error-admin。
先按提示中的文件与组件定位，区分以下情况：
- 启动或 reload 时报页面配置错误：检查对应 yml 字段、脚本及完整错误原因，修正后再重新载入。
- 页面打开后才出现运行异常：记录触发步骤，并保留服务端该条提示及同一时间客户端
logs/latest.log的完整异常。替换页面已回退原版时，也继续从最早的错误查起。 - 编辑器保存被拒绝：按保存结果中的页面、字段与原因修正草稿，不能用反复打开页面代替处理保存错误。
- 只出现
not_ready：按上方就绪排错检查握手与版本，它与具体页面的运行错误是不同阶段。
反馈时一并注明实际运行的双端版本、Minecraft 与加载器、是否经过代理，以及最短复现步骤。截图可以辅助说明，但需要日志保留完整原因。
启动时提示缺少前置
确认 ChaCore 已放入 plugins/，并且版本适用于当前服务器。修正后完整重启服务器。
没有生成 ChaUI 文件夹
先检查控制台中的 ChaUI 启动错误。常见原因包括 Java 版本不正确、ChaCore 未安装或插件文件与服务器版本不匹配。只有插件正常启用后，默认文件才会生成。
没有看到备份目录
备份目录在页面发生覆盖保存时才需要使用。新安装且尚未覆盖过页面时，没有备份文件属于正常情况。
页面能打开，但图片或音效缺失
普通页面的图片和音效来自客户端本地资源，不会由服务端插件自动发送。请检查客户端的 resourcepacks/ChaUI/ 目录，并确保所有玩家获得了相同素材。原版菜单页面还会先读取当前活动页面包内由 vanilla-menu-assets/** 发布的素材；若包内缺失，再回退到 ChaAssets 或客户端本地目录，具体见页面包与素材。
是否需要自己编写页面 yml
不需要。推荐直接使用游戏内编辑器创建和保存页面，ChaUI 会自动生成对应文件。页面 yml 主要用于备份、迁移和高级维护。