猹件开发组命令参考
ChaEngine 的标准根命令是 /chaengine，/cengine 是同一个命令的短别名。本文统一使用标准写法，并以服务端当前注册的命令为准。
命令框架只区分“任意游戏内玩家”和“管理员玩家或控制台”，没有独立的 ChaEngine 权限节点：
| 标记 | 可执行者 | 说明 |
|---|---|---|
| 玩家 | 任意游戏内玩家 | 控制台和命令方块不能执行 |
| 管理员或控制台 | OP 玩家、控制台或命令方块 | 普通玩家不会看到或执行这些命令 |
| 所有人 | 玩家、控制台或命令方块 | 仅用于查看帮助 |
如果服务器需要更细的授权，应由上层命令或权限插件包装，不能填写一个并不存在的 chaengine.* 权限节点。
参数格式
| 参数 | 格式与行为 |
|---|---|
<id> | 对应配置中的方块、物品、实体或时装 ID；支持的命令会提供补全 |
<player> | 方块、物品发放命令使用在线玩家的精确名称；时装命令还接受在线玩家 UUID |
<location> | 推荐写成 世界名,X,Y,Z，四项以英文逗号分隔，坐标必须是整数，例如 world,120,64,-35 |
<entity> | 实体 UUID 或当前运行期数字 ID；玩家执行时还可使用 @aim、@nearest |
<animation> | 客户端动画文件中实际存在的动画 ID；名称不能是空字符串 |
<#RRGGBB> | 严格的六位十六进制 RGB 颜色，必须带 #，例如 #33CCFF；不接受三位缩写、透明度或颜色名称 |
<temporary|permanent> | temporary 是当前运行期临时覆盖，permanent 会写入实体自身数据 |
<perspective> | first、third_back、third_front 或 second；second 是正面第三人称的别名 |
<lock> | true 时禁止玩家主动切换视角，false 时允许；省略时默认为 false |
<session> | 播放场景成功后返回的会话 UUID，用于只停止指定场景 |
相机管理操作还会使用在线玩家、视角、布尔锁定、预设 ID、场景 ID 与可选会话 UUID。视角接受第一人称、背面第三人称、正面第三人称，以及正面第三人称的 second 别名；预设和场景 ID 来自对应配置目录的相对路径。
@aim 选择准星 64 格内首先命中的其他生物；@nearest 选择同世界最近的有效生物，不包含执行者。两者依赖玩家位置和视角，控制台不能使用。数字实体 ID 会随运行状态变化，自动化脚本优先使用 UUID。
实体模型模式省略时默认 temporary。解析器也接受 temp、false、临时 和 perm、true、永久，但新文档和脚本应只使用 temporary、permanent。
帮助
| 命令 | 调用者 | 结果 |
|---|---|---|
/chaengine help | 所有人 | 显示调用者当前可用的命令 |
/chaengine help <page> | 所有人 | 显示指定页；<page> 应填写整数页码 |
直接输入 /chaengine 但不带有效参数时也会返回可用命令帮助。
重载配置
/chaengine reload- 调用者：管理员或控制台。
- 结果：重新读取服务端配置，并向在线客户端重新同步模型、时装和按键定义。
- 不会执行：不会创建、上传或更新客户端模型、动画和贴图资源。
- 排错：YAML 加载问题查看服务端日志；客户端资源缺失按资源目录检查。
方块模型
| 命令 | 调用者 | 结果与拒绝条件 |
|---|---|---|
/chaengine block get <id> | 玩家 | 把一个模型方块载体发给执行者；模型 ID 不存在或物品创建失败时拒绝 |
/chaengine block give <id> <player> | 管理员或控制台 | 发给指定在线玩家；玩家不在线或模型 ID 不存在时拒绝 |
/chaengine block set <id> <location> | 管理员或控制台 | 把模型 ID 写入指定载体方块自身数据；位置无效、模型不存在或目标不是受支持载体时拒绝 |
/chaengine block debug settarget <id> | 玩家 | 把模型 ID 写入八格内准星指向的玩家头颅并回显读取结果，仅用于开发排查 |
/chaengine block animation play <location> <animation> | 管理员或控制台 | 对指定模型方块播放特殊动画；位置或载体无效、动画名为空时拒绝 |
/chaengine block animation stop <location> | 管理员或控制台 | 停止指定模型方块动画并进入显式无动画状态；位置或载体无效时拒绝 |
常用示例：
/chaengine block get blue_crystal
/chaengine block give blue_crystal Steve
/chaengine block set blue_crystal world,120,64,-35
/chaengine block animation play world,120,64,-35 idle
/chaengine block animation stop world,120,64,-35位置参数只负责找到要操作的方块。模型 ID 必须保存在载体方块自身数据中，不存在“坐标到模型 ID”的映射或兜底。
服务端只检查方块动画名是否为空，不会读取客户端动画文件。动画 ID 拼写错误时命令仍可能成功，但客户端没有可播放内容。
物品模型
| 命令 | 调用者 | 结果与拒绝条件 |
|---|---|---|
/chaengine item get <id> | 玩家 | 把一个模型物品发给执行者；ID 不存在或物品创建失败时拒绝 |
/chaengine item give <id> <player> | 管理员或控制台 | 向指定在线玩家发放一个模型物品 |
/chaengine item give <id> <player> <amount> | 管理员或控制台 | 向指定在线玩家发放指定数量；数量无法解析或小于 1 时按 1 处理 |
/chaengine item get bronze_charm
/chaengine item give bronze_charm Steve
/chaengine item give bronze_charm Steve 3玩家离线、物品 ID 不存在或物品创建失败时，发放命令会返回失败结果。
实体模型
| 命令 | 调用者 | 结果与拒绝条件 |
|---|---|---|
/chaengine entity model set <entity> <id> | 管理员或控制台 | 临时强制指定实体模型；默认模式是 temporary |
/chaengine entity model set <entity> <id> <temporary|permanent> | 管理员或控制台 | 按指定模式设置实体模型；实体、模型 ID 或模式无效时拒绝 |
/chaengine entity model clear <entity> | 管理员或控制台 | 清除临时和永久强制模型，恢复客户端 match 规则 |
/chaengine entity glow set <entity> <#RRGGBB> | 管理员或控制台 | 为生物实体设置所有玩家可见的自定义颜色描边；目标不是生物或颜色格式错误时拒绝 |
/chaengine entity glow clear <entity> | 管理员或控制台 | 清除自定义描边颜色并恢复原版发光与队伍颜色规则；目标不是生物时拒绝 |
完整语法：
/chaengine entity model set <entity> <id>
/chaengine entity model set <entity> <id> <temporary|permanent>
/chaengine entity model clear <entity>
/chaengine entity glow set <entity> <#RRGGBB>
/chaengine entity glow clear <entity>/chaengine entity model set @aim crystal_guardian temporary
/chaengine entity model set 550 crystal_guardian permanent
/chaengine entity model clear @aim
/chaengine entity glow set @aim #33CCFF
/chaengine entity glow set 550 #FF6600
/chaengine entity glow clear @nearestpermanent 会把模型 ID 写入实体自身的 ChaEngine 数据，实体卸载再加载后仍可恢复；它不是坐标映射。较高优先级保存了不存在的模型 ID 时，客户端会失败关闭该强制结果，不擅自回退到其他模型。
荧光命令与模型选择相互独立，实体 UUID、当前运行期数字 ID、@aim 和 @nearest 的解析规则相同。重复执行 set 会覆盖该实体上一种自定义颜色；对没有自定义颜色的有效生物执行 clear 也是幂等成功。自定义描边只保存在当前运行期，实体卸载、切换维度、插件重载或服务器重启后需要重新设置。
实体动画
| 命令 | 调用者 | 结果与拒绝条件 |
|---|---|---|
/chaengine entity animation play <entity> <animation> | 管理员或控制台 | 播放特殊动画并覆盖自动状态动画；实体无效或动画名为空时拒绝 |
/chaengine entity animation stop <entity> | 管理员或控制台 | 删除特殊动画覆盖，恢复客户端自动状态动画；实体无效时拒绝 |
/chaengine entity animation play @aim attack
/chaengine entity animation stop @aim服务端不会读取客户端动画文件，因此名称非空时可能返回成功，但客户端仍可能因为动画 ID 拼错或资源缺失而没有画面。
玩家时装
| 命令 | 调用者 | 结果与拒绝条件 |
|---|---|---|
/chaengine equip add <player> <id> | 管理员或控制台 | 给在线玩家添加时装；同一部位已有时装时替换活动时装 |
/chaengine equip remove <player> <id> | 管理员或控制台 | 按时装配置的部位移除指定时装 |
/chaengine equip clear <player> | 管理员或控制台 | 清空玩家全部部位的当前时装状态 |
/chaengine equip add Steve traveler_backpack
/chaengine equip remove Steve traveler_backpack
/chaengine equip clear Steve这些命令维护的是当前服务端进程内可重同步的穿戴状态，不会自动写入数据库。跨完整重启保存时，应由业务插件持久化玩家选择，并在上线后通过 Java API 恢复。
兼容入口
旧脚本仍可使用以下兼容入口：
/chaengine entity equip add <player> <id>
/chaengine entity equip remove <player> <id>
/chaengine entity equip clear <player>新教程、脚本和命令补全统一使用较短的 /chaengine equip ... 标准入口；兼容入口不在其他教程重复展示。
相机
相机管理能力均由管理员或控制台对在线玩家执行：
| 命令 | 结果与拒绝条件 |
|---|---|
/chaengine camera perspective <player> <perspective> | 切换第一/第三人称且不锁定玩家主动切换；玩家不在线或视角无效时拒绝 |
/chaengine camera perspective <player> <perspective> <lock> | 切换视角并明确设置是否锁定；<lock> 不是 true 或 false 时拒绝 |
/chaengine camera preset apply <player> <id> | 应用 camera/presets/ 下的预设；预设不存在或客户端不支持时拒绝 |
/chaengine camera scene play <player> <id> | 播放 camera/scenes/ 下的场景并返回会话 UUID；场景不存在时拒绝 |
/chaengine camera scene stop <player> | 停止该玩家当前最高优先级的场景，不清除普通相机控制或预设 |
/chaengine camera scene stop <player> <session> | 只停止指定会话 UUID；UUID 无效或会话不存在时拒绝 |
/chaengine camera scene interrupt <player> | 打断该玩家当前最高优先级的可打断场景，并播放 interrupt 衔接 |
/chaengine camera scene interrupt <player> <session> | 只打断指定场景会话；不支持新场景生命周期能力时拒绝且不降级为 stop |
/chaengine camera reset <player> | 清空该玩家全部远程相机会话并恢复原视角与输入 |
/chaengine camera status <player> | 显示客户端是否支持相机、能力状态与当前活动会话数 |
常用示例：
/chaengine camera perspective Steve third_back true
/chaengine camera perspective Steve first false
/chaengine camera preset apply Steve combat-shoulder
/chaengine camera scene play Steve intro
/chaengine camera scene stop Steve
/chaengine camera scene stop Steve 5f9f25d5-1b5e-4c3d-bb20-998f08e72147
/chaengine camera scene interrupt Steve
/chaengine camera scene interrupt Steve 5f9f25d5-1b5e-4c3d-bb20-998f08e72147
/chaengine camera reset Steve
/chaengine camera status Steve场景会话 UUID 应从播放成功结果中取得，不要手工编造。stop 表示由管理员停止，interrupt 表示独立打断并产生 INTERRUPTED 状态；二者都不会清除普通视角控制或相机预设。需要完全恢复时使用相机重置。