页面包与素材 ​

原版菜单可能在玩家尚未进服时出现，因此它不能只依赖当前服务器会话。ChaUI 使用一套“活动菜单包”：客户端启动先加载上一套有效包或定制客户端预置包，进服后再与服务器比较并安全更新。

服务端准备目录 ​

plugins/ChaUI/
├─ pages/
│  ├─ tutorial_pause_menu.yml
│  └─ menus/
│     └─ fixed_server_title.yml
└─ vanilla-menu-assets/
   ├─ gui/
   │  └─ menu/background.png
   ├─ fonts/menu.ttf
   └─ sounds/menu-click.ogg

• pages/** 继续存放全部 ChaUI 页面；只有通过校验且声明 display.mode: vanilla 的页面会进入菜单包。
• vanilla-menu-assets/** 只存放要随菜单包同步的素材，目录结构与客户端 resourcepacks/ChaUI 相同。
• 页面中的素材路径仍写 gui/menu/background.png，不要加 vanilla-menu-assets/ 或包内的 assets/ 前缀。
• 符号链接、越出目录的路径和非普通文件不会进入发布包。

生成后的完整包按以下逻辑组织；该结构由 ChaUI 发布流程维护：

菜单包.zip
├─ manifest.json
├─ pages/
│  ├─ tutorial_pause_menu.yml
│  └─ menus/fixed_server_title.yml
└─ assets/
   ├─ gui/menu/background.png
   ├─ fonts/menu.ttf
   └─ sounds/menu-click.ogg

什么时候会发布新包 ​

/chaui reload 会先校验页面和素材，再生成一份不可变快照。客户端完成就绪后会报告当前活动包摘要；摘要相同则不重复发送，不同才接收新候选包。

导出定制客户端的预置包 ​

服务器同步使用的快照默认保存在内存中。需要制作定制客户端时，先保存页面并按需执行 /chaui reload，确认当前页面和素材已经发布，再执行：

/chaui menupack export

控制台会返回导出路径，固定文件为：

plugins/ChaUI/vanilla-menu-bootstrap.zip

这个文件就是当前已发布快照的完整 ZIP，已经包含 manifest.json、页面、素材和校验摘要。把它复制到目标客户端并改成以下文件名：

.minecraft/chaui/vanilla-menu/bootstrap.zip

不要自行把 pages/ 和素材目录压缩后冒充预置包；也不要在导出后继续手工修改 ZIP。页面或素材变化后，应重新发布并再次执行导出命令。

客户端接收与切换 ​

新包以每片最多 24576 字节自动传输。客户端完整收到后会一次检查：

• 压缩包、清单和整体摘要；
• 每个文件的路径、长度和 SHA-256；
• 重复条目、文件数量和大小限制；
• 页面是否为无 BOM UTF-8；
• 页面 Schema、脚本、目标以及同目标冲突。

只有整个候选包都通过后，活动包才会一次切换。中途断线、摘要不一致、YAML 损坏或脚本不合法都不会暴露半套新页面；客户端继续使用上一套有效包。

当前限制如下：

大型视频很容易占满同步包。优先把视频随定制客户端放入本地资源目录，或通过 ChaAssets 分发；菜单包更适合页面、图片、字体和短音效。

客户端启动目录 ​

.minecraft/chaui/vanilla-menu/
├─ bootstrap.zip
├─ active
└─ packs/
   └─ <sha256>/
      ├─ manifest.json
      ├─ pages/
      └─ assets/

• bootstrap.zip：定制客户端可选的预置菜单包，适合玩家第一次联网前显示标题菜单。
• packs/<sha256>/：客户端保存的、已经完整校验过的菜单包内容。
• active：当前活动包的摘要指针。

启动时先校验 active 指向的缓存包。只有活动指针缺失、非法或缓存损坏时，才尝试导入 bootstrap.zip。服务器包一旦成功成为活动包，之后启动不会因为 bootstrap.zip 仍存在而覆盖它；活动缓存后来损坏时才可能再次回退预置包。

bootstrap.zip 必须来自上面的 /chaui menupack export，不能只是把 pages/ 与素材随意压缩。没有可验证预置包时可以不提供：客户端会保留原版标题页面，并在首次连接服务器后接收有效菜单包。不要手工编辑 active 或 packs/<sha256>/。

客户端本地资源目录 ​

.minecraft/resourcepacks/ChaUI/
├─ gui/menu/background.png
├─ fonts/menu.ttf
├─ sounds/menu-click.ogg
└─ video/intro.mp4

原版菜单查找相对素材时，顺序为：

1. 当前活动菜单包的 assets/；
2. ChaAssets 提供的 ChaUI 资源；
3. 客户端 resourcepacks/ChaUI。

因此服务器可以在活动包中覆盖定制客户端的旧背景；活动包没有该路径时，仍能使用 ChaAssets 或客户端本地素材。普通 screen、HUD、world 和 container 页面不会意外继承菜单包素材作用域。

热切换时当前页面会怎样 ​

玩家正在使用替换菜单时激活新包，旧页面只执行一次正常 close 和资源释放。ChaUI 会在保留的原版上下文上重建新替换页；新包没有该目标或重建失败时，立即恢复原版页面。玩家不需要重启客户端，也不会看到新旧素材混用的半包状态。

具体失败现象和应看到的回退结果见安全回退与排错。