命令参考 ​

ChaEngine 的标准根命令是 /chaengine，/cengine 是同一个命令的短别名。本文统一使用标准写法，并以服务端当前注册的命令为准。

命令框架只区分“任意游戏内玩家”和“管理员玩家或控制台”，没有独立的 ChaEngine 权限节点：

如果服务器需要更细的授权，应由上层命令或权限插件包装，不能填写一个并不存在的 chaengine.* 权限节点。

动作编辑器另外检查 actions.editor.whitelist，即使是 OP 也必须列入白名单。

更新插件后，lang.yml 中尚未填写的新提示会使用插件内默认文案；已有自定义文案优先，语言文件不会被整份覆盖。

参数格式 ​

相机管理操作还会使用在线玩家、视角、布尔锁定、预设 ID、场景 ID 与可选会话 UUID。视角接受第一人称、背面第三人称、正面第三人称，以及正面第三人称的 second 别名；预设和场景 ID 来自对应配置目录的相对路径。

@aim 选择准星 64 格内首先命中的其他生物；@nearest 选择同世界最近的有效生物，不包含执行者。两者依赖玩家位置和视角，控制台不能使用。数字实体 ID 会随运行状态变化，自动化脚本优先使用 UUID。

实体模型模式省略时默认 temporary。解析器也接受 temp、false、临时 和 perm、true、永久，但新文档和脚本应只使用 temporary、permanent。

帮助 ​

直接输入 /chaengine 但不带有效参数时也会返回可用命令帮助。

重载配置 ​

/chaengine reload

• 调用者：管理员或控制台。
• 结果：重新读取服务端配置，并向在线客户端重新同步模型、时装和按键定义。
• 同时读取服务端动画库，重新检查编辑白名单，并同步人物动作、独立播放组和映射；重载会清理旧播放状态。旧 humanoid.json 自动备份迁移；首次转换时纳入旧 actions/animations/ 标准文件。工作室首次保存后，以保存的库为准，不再扫描游离旧文件。校验失败时保留上一份有效数据，保存进行中则暂不重载动作数据。制作步骤见动作工作室。
• 不会执行：不会创建、上传或更新客户端模型、动画和贴图资源。
• 更新插件 Jar 后需要完整重启服务器，本命令不能使新 Jar 代码生效。若出现 This registration already exists，按重载异常排查核对实际运行包。
• 排错：YAML 加载问题查看服务端日志；客户端资源缺失按资源目录检查。

打开动作编辑器 ​

/chaengine action editor

• 调用者：actions.editor.whitelist 中的游戏内玩家，填写玩家名或 UUID；空列表禁止编辑，OP 没有例外。
• 结果：读取服务器动画库并打开动作工作室。F6 不再打开编辑器。
• 客户端必须安装匹配的 ChaEngineMod，并完成进服同步；提示未就绪时等待同步后重试。
• 导入直接保存到服务器；“保存到服务器”或 Ctrl+S 保存编辑结果，收到成功提示后生效。白名单变更通过 /chaengine reload 重载。
• 完整配置、素体导入预览和动画骨架形式见动作工作室。

播放玩家动画 ​

/chaengine action play <玩家名> <动画名>

例如服务器动画库中已有“后翻滚”，让在线玩家 Steve 播放：

/chaengine action play Steve 后翻滚

• 调用者：管理员或控制台；普通玩家不能借此绕过技能权限。
• 动画名填写动画库中的实际名称，支持中文和空格；不要填写分类名或文件路径。
• 自动选择玩家当前实体模型；没有实体模型时，优先使用已配置的整身时装，否则使用当前首个时装。需要明确选择某个时装时使用Java API。没有实体 / 时装模型时拒绝，不修改玩家外观。
• 目标必须在线、安装配套客户端并完成动画同步。未知动画、未支持的数据会明确拒绝。
• 单次动画结束后恢复基础人物动作，独立装饰分组继续播放。此命令只播放视觉动作，不移动玩家坐标，不执行伤害或攻击判定。
• 播放时遵守动画的“允许移动”和“允许转动视角”独立设置；循环或保持末帧动画的限制会持续到停止。停止人物动画不会解除其他仍在播放分组的限制，见动作控制。
• 成功消息表示已经提交播放，不代表客户端已经显示正确；骨骼缺失时跳过，骨架形式需要与模型兼容。
• 编辑白名单玩家也可在工作室点击“在自己身上试播”，该按钮只作用于本人，不要求 OP。制作与模型范围见动作工作室。

停止玩家动画 ​

/chaengine action stop <玩家名>

/chaengine action stop Steve

调用者为管理员或控制台。停止当前实体 / 时装模型的主动人物动画，恢复基础动作；不停止独立装饰组，也不删除动画或规则。循环或保持末帧的主动动画可通过此命令结束。

生成玩家模型残影 ​

/chaengine action afterimage <玩家名> <颜色> <存留秒数> [数量] [间隔秒数]

管理员或控制台可用。直接记录玩家当前模型的姿态和位置，无须给动画配置特效，也不会中断动作、产生伤害或改变玩家坐标。

/chaengine action afterimage Steve #BDEFFF 0.5
/chaengine action afterimage Steve #BDEFFF 0.5 6
/chaengine action afterimage Steve #80FFAA44 0.6 8 0.08

第一条生成 1 道冷青色残影；第二条每隔默认的 0.08 秒采样，共 6 道；第三条一次提交 8 道约 50% 不透明度的暖橙色残影，每道在生成后 0.6 秒内淡出。多道残影记录各自生成时刻的姿态，不是把同一张姿态重复复制。

整个批次只提交一次，由客户端从首次成功采样开始统一计时。后续采样不会累积前一次的帧延迟；错过采样点时跳过，不补生成重叠的旧姿态。实际数量可能因帧率、模型不可见或性能限制而减少。不同观察者可能有网络延迟，不保证同一绝对时刻开始。

目标为玩家当前实体替换模型，或隐藏原人物的全身时装模型。不作用于原版皮肤、局部时装或第一人称手部；残影记录模型本体，手持武器使用动画的武器拖影。请切换第三人称并移动，或让附近玩家观察；静止残影会与本体重合。只向同世界 128 格内已同步且可见该玩家的客户端提交。成功提示表示已提交，不能代替画面确认。目标模型切换、离开视野或切换世界后，不继续补采样旧模型。

未更新的客户端不能接收此能力；请同时更新本批次服务端与客户端，并完整重启。插件技能可调用 模型残影 API，动画内的特效设置见动作工作室。

方块模型 ​

常用示例：

/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 bronze_charm
/chaengine item give bronze_charm Steve
/chaengine item give bronze_charm Steve 3

玩家离线、物品 ID 不存在或物品创建失败时，发放命令会返回失败结果。

实体模型 ​

完整语法：

/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 @nearest

permanent 会把模型 ID 写入实体自身的 ChaEngine 数据，实体卸载再加载后仍可恢复；它不是坐标映射。较高优先级保存了不存在的模型 ID 时，客户端会失败关闭该强制结果，不擅自回退到其他模型。

荧光命令与模型选择相互独立，实体 UUID、当前运行期数字 ID、@aim 和 @nearest 的解析规则相同。重复执行 set 会覆盖该实体上一种自定义颜色；对没有自定义颜色的有效生物执行 clear 也是幂等成功。自定义描边只保存在当前运行期，实体卸载、切换维度、插件重载或服务器重启后需要重新设置。

实体动画 ​

/chaengine entity animation play @aim attack
/chaengine entity animation stop @aim

服务端不会读取客户端动画文件，因此名称非空时可能返回成功，但客户端仍可能因为动画 ID 拼错或资源缺失而没有画面。

玩家时装 ​

/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 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 状态；二者都不会清除普通视角控制或相机预设。需要完全恢复时使用相机重置。

配置和恢复规则见相机系统、相机预设与场景镜头。

相关文档 ​

• 第一个方块模型
• 第一个物品模型
• 第一个实体模型
• 模型动画
• 相机系统
• 玩家时装
• 常见问题与排错