插件指令 ​

ChaUI 的主指令是 /chaui，也可以使用简写 /cui。指令用于打开编辑器、向玩家展示页面、管理世界页面实例，以及重新载入页面配置。

大部分管理指令需要由服务器控制台或拥有管理员权限的玩家执行。编辑器指令只能由游戏内玩家使用，并且需要编辑权限。

查看指令帮助 ​

直接输入：

/chaui

游戏会列出当前可用的子指令和参数提示。

执行服务端通用方法 ​

为一名在线玩家启动 global-scripts.yml 中的方法：

/chaui script <玩家> <方法> [参数...]

例如方法 notify_player 声明了一个字符串参数：

/chaui script Steve notify_player 欢迎回来

参数按方法中的声明顺序传入，每个空格分隔项对应一个参数。目标玩家必须在线，方法必须已经通过 /chaui reload 加载；参数数量与 string、number、boolean 类型不匹配时会明确拒绝。

执行成功会返回唯一执行 ID。没有 timer 或 interval 的同步方法可能在命令返回时已经完成；包含周期任务的方法会保持活动，直到脚本自行取消、玩家离线或管理员停止。

列出当前仍在运行的根执行：

/chaui script list

每一行都会显示执行 ID、目标玩家或控制台、根方法、来源类型和来源 ID。来源类型包括 command、api、page 与 cron；页面来源 ID 是发起调用的页面 ID，Cron 来源 ID 是 Cron 配置 ID。已经同步完成或已经停止的执行不会出现在列表中。

强制停止一项仍在运行的执行：

/chaui script stop <执行ID>

<执行ID> 支持补全当前活动 ID。停止会一并取消这项根执行的子方法和计时任务。ID 不存在、已经完成或已经停止时只提示未找到，不会影响其他脚本。完整的配置、PAPI 快照和 Cron 用法见服务端通用脚本与 Cron。

打开页面编辑器 ​

/chaui editor <页面ID>

页面已经存在时会打开对应页面；页面不存在时，会以这个 ID 创建一个空白页面并进入编辑器。

例如：

/chaui editor welcome

页面 ID 会同时作为页面文件名使用。建议选择简短、容易识别的名称。

打开普通页面或 HUD ​

/chaui open <玩家> <页面ID>

这个指令用于打开 screen 普通页面和 hud 页面。世界页面需要使用专门的世界页面指令。

打开世界页面 ​

使用页面中已经保存的位置、缩放和朝向：

/chaui openworld <玩家> <页面ID> <实例ID>

临时覆盖页面位置和朝向：

/chaui openworld <玩家> <页面ID> <实例ID> <x> <y> <z> <yaw>

临时覆盖位置、水平朝向和倾角：

/chaui openworld <玩家> <页面ID> <实例ID> <x> <y> <z> <yaw> <pitch>

yaw 可以填写有限数字，也可以填写 follow_player，让页面始终水平朝向当前玩家。pitch 必须是有限数字：0 保持竖直，90 正面朝上横放，-90 正面朝下。省略位置时使用页面保存的 pitch；使用旧的完整格式时 pitch 为 0。实例 ID 是当前玩家全部世界页面共用的实例名称，可以使用纯数字、中文或常用符号，例如 111、大厅提示、宝箱-1。

管理全服常驻世界页面 ​

把世界页面加入全服常驻列表，并使用页面保存的默认位置与朝向：

/chaui addworld <世界> <页面ID> <实例ID>

也可以为这个常驻实例单独指定位置与朝向：

/chaui addworld <世界> <页面ID> <实例ID> <x> <y> <z> <yaw>

也可以在末尾添加倾角：

/chaui addworld <世界> <页面ID> <实例ID> <x> <y> <z> <yaw> <pitch>

短格式读取页面保存的 pitch；旧的完整格式使用 pitch: 0；带 pitch 的完整格式可以创建横放或倾斜的常驻页面。

常驻实例会保存到服务端 plugins/ChaUI/persistent-world-pages.yml。位于目标世界的玩家完成 ChaUI 客户端就绪握手后会自动看到它；玩家离开目标世界时实例自动关闭，重新进入时自动恢复。常驻实例 ID 在整张全服常驻列表中唯一，不能在两个世界重复使用同一个 ID。

查看当前注册记录：

/chaui listworlds

永久删除常驻记录：

/chaui removeworld <实例ID>

closeworld 只临时关闭某一个玩家当前看到的实例，不会删除常驻记录；该玩家重新进入目标世界或重新进服后仍会恢复。需要让所有玩家都不再自动打开时，应使用 removeworld。

关闭页面 ​

在玩家当前普通 GUI 或容器替换 GUI 上方打开一层 screen 子页面：

/chaui opensub <玩家> <页面ID>

只关闭当前最上层子页面：

/chaui closesub <玩家>

子页面最多叠加 8 层，不能把当前父子链里已经存在的页面再次打开。父页面和子页面默认都可以点击；模态遮罩由子页面自己的 pointerEvents: block 组件控制。完整示例见在 GUI 上打开子页面。

关闭普通页面、HUD 或世界实例 ​

关闭普通页面或 HUD：

/chaui close <玩家> <页面ID>

关闭指定世界页面实例：

/chaui closeworld <玩家> <实例ID>

世界实例 ID 在同一玩家当前打开的全部世界页面中全局唯一。关闭时只需填写打开时使用的实例 ID，不需要再填写页面 ID。

世界页面中的按钮同样支持准星悬浮和左、右、中键事件。按钮脚本使用无参数 关闭() / close() 时，会关闭当前被点击的世界实例。

播放页面音效 ​

/chaui sound <玩家> <页面ID> <音效路径>

音效路径使用 ChaUI 素材根目录下的相对路径，例如 sounds/click.ogg。目标客户端必须已经能从 ChaAssets、普通本地目录或当前原版菜单活动包中解析到对应 OGG；这条指令本身不会临时发送音效文件。

重置玩家的组件位置 ​

当玩家希望恢复页面作者设置的默认位置时，可以重置这个玩家在当前服务器下记住的全部组件位置：

/chaui resetpositions <玩家>

目标玩家必须在线，并且客户端已经完成 ChaUI 就绪握手。成功后，当前打开页面中的对应组件会立即回到原始布局位置；以后再次打开页面也不会继续使用旧记忆。这个操作不会修改页面 yml，不会重置其他玩家，也不会删除该玩家在其他服务器中的位置记录。

如果只想重置当前页面中的某一个组件，可以在按钮脚本中使用 component("组件ID").resetPosition()。完整用法见组件对象、布局公式与临时组件。

重新载入 ChaUI ​

/chaui reload

这条指令会统一重新载入并发布以下内容：

• 重新读取普通页面、容器页面、HUD、世界页面和插件配置；当前已经打开的普通页面、HUD 和世界页面会按完整关闭后重新打开的方式刷新，因此页面生命周期事件也会正常执行；
• 重新读取 global-scripts.yml，让后续命令、页面、API 调用使用新方法，并按新 Cron 时间表调度；已经启动的通用脚本继续使用启动时快照；
• 从所有校验通过的 display.mode: vanilla 页面和 vanilla-menu-assets/** 重新构建原版菜单页面包，并向已经就绪且摘要不同的客户端发布；候选包构建失败时继续保留上一份有效包。

直接修改 pages/**、global-scripts.yml 或 vanilla-menu-assets/** 后都需要执行本指令。游戏内编辑器成功保存原版菜单页面时会立即重建并发布页面包，不需要再额外 reload；编辑器不会上传管理员客户端本地素材，手工增删 vanilla-menu-assets/** 后仍需 reload。

导出原版菜单预置包 ​

把当前已经发布的原版菜单页面包导出为可分发文件：

/chaui menupack export

该指令可由控制台或管理员执行，输出固定为 plugins/ChaUI/vanilla-menu-bootstrap.zip。把它复制到定制客户端的 .minecraft/chaui/vanilla-menu/bootstrap.zip，即可让玩家在第一次连接服务器前使用预置替换菜单。页面或 vanilla-menu-assets/** 发生变化后，应先保存或执行 /chaui reload，再重新导出。完整目录与校验规则见页面包与素材。

常见问题 ​

提示玩家不在线 ​

检查玩家名是否完全一致，并确认目标玩家已经进入服务器。

提示页面不存在 ​

先在 plugins/ChaUI/pages/ 中确认页面文件存在，或使用编辑器创建并保存页面，然后重新载入 ChaUI。

普通打开指令不能打开世界页面 ​

这是正常的。世界页面支持位置、朝向和多实例，需要使用 openworld。

世界页面实例 ID 提示不合法 ​

实例 ID 不能为空，最多 64 个 Unicode 字符，并且不能包含换行等控制字符。纯数字 ID 可以直接使用。

常驻世界页面没有自动出现 ​

确认记录中的世界名与 Bukkit 实际世界名完全一致，并用 listworlds 检查页面 ID、坐标、yaw 和 pitch。记录引用的页面必须已经加载且为 display.mode: world；无效记录会保留在配置中，但在修复页面或世界前不会打开。

页面打开了但图片缺失 ​

打开指令本身不会临时分发客户端素材。普通页面请按照客户端安装检查 ChaAssets 或本地目录；原版菜单页面还应检查页面包与素材中的活动包与 vanilla-menu-assets/** 发布流程。

Tooltip 编辑器 ​

/chaui tooltipeditor 打开服务器全局 Tooltip 编辑器，需要在线玩家与 chaui.tooltipeditor 权限。编辑器使用独占租约；已被其他管理员占用时会显示占用者，不允许多人同时编辑。存在活动页面或 Tooltip 编辑租约时，/chaui reload 会拒绝执行。

详细操作见使用 Tooltip 编辑器。