自定义指令
开发者可以通过在行为包中配置 JSON 来添加自定义指令。添加的自定义指令支持在聊天栏预览和 Tab 补全，支持与指令相关的所有事件及接口。通过 ModSDK 脚本监听指令触发事件，可以实现自定义的指令逻辑。
Demo
参考官方示例 CustomCommandDemo 了解自定义指令的完整实现。
概述
自定义指令系统提供以下功能：
- 通过 JSON 注册新指令并定义参数
- 支持多种参数类型（浮点数、整数、布尔值、字符串、目标选择器、坐标等）
- 支持在聊天栏输入时的 Tab 自动补全
- 支持参数默认值
- 支持参数变体（最多 10 套参数组合）
- 通过脚本事件回调处理指令执行逻辑
待补充：自定义指令与原版指令系统的交互说明。
指令 JSON 配置（netease_commands/）
在行为包的 behavior 目录下新建 netease_commands/ 目录，创建指令定义的 JSON 文件。
文件命名
JSON 文件命名推荐格式为 团队名_模组命名空间_指令名称，例如 myTeam_myMod_explode.json。文件名应使用英文、数字和下划线，不可含有中文和特殊字符。
基本格式
{
"format_version": "0.0.1",
"name": "mycommand",
"description": "我的自定义指令",
"permission_level": "game_directors",
"args": [
{"name": "目标", "type": "target"},
{"name": "数量", "type": "int", "default": 1}
]
}顶层字段说明
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
format_version | string | — | 格式版本，请填写 0.0.1 |
name | string | — | 指令名称 |
description | string | — | 指令描述，支持在 zh_CN.lang 中定义 |
permission_level | string | game_directors | 权限等级 |
待补充：指令名称的命名规范与限制。
指令参数类型
args 数组中每个对象定义一个参数，参数的输入顺序由数组顺序决定。
| 参数类型 | type 值 | 说明 |
|---|---|---|
| 浮点数 | float | 浮点数值 |
| 整数 | int | 整数值 |
| 布尔值 | bool | true 或 false |
| 字符串 | str | 文本字符串 |
| 目标选择器 | target | 如 @s、@a、@p |
| 坐标 | pos | 三维坐标 [x, y, z] |
| 实体类型 | entity | 实体标识符 |
| 物品类型 | item | 物品标识符 |
注意
含有 default 的参数必须排在参数列表的尾部，且在游戏中可以不传。default 值不必和 type 的类型符合。
待补充：各参数类型的详细输入格式与验证规则。
Tab 补全
自定义指令在聊天栏中输入 / 后会自动出现在指令提示列表中，输入指令名后参数会按照 args 中定义的顺序依次提示。
待补充：Tab 补全的行为细节与自定义提示文本。
脚本回调处理
开发者需要监听 CustomCommandTriggerServerEvent 事件来为自定义指令编写执行逻辑。
# 监听自定义指令事件
self.ListenForEvent(serverApi.Engine, serverApi.Engine,
'CustomCommandTriggerServerEvent', self, self.OnCustomCommand)
def OnCustomCommand(self, args):
command_name = args.get("command")
# 处理指令逻辑相关接口与事件
| 名称 | 类型 | 说明 |
|---|---|---|
CustomCommandTriggerServerEvent | 事件 | 自定义指令触发时回调 |
SetCommand | 接口 | 通过脚本触发指令 |
GlobalCommandServerEvent | 事件 | 监听所有指令（含自定义） |
待补充：事件参数详细说明、variant 字段用法。
权限控制
通过 permission_level 字段控制指令的使用权限：
| 值 | 说明 |
|---|---|
game_directors | 任何操作员可运行（含命令方块） |
admin | 任何操作员可运行（不含命令方块） |
host | 仅服务器主机可运行 |
owner | 仅专用服务器可运行 |
any | 任何人可运行 |
待补充：权限等级与游戏模式的关系说明。
配置变体
通过 args1、args2 ... args9 可以额外配置多套参数组合，加上原来的 args，最多支持 10 套参数变体。玩家发送指令时，系统会自动匹配参数并通过 variant 字段标识使用了哪一套参数。
待补充：参数变体配置示例与 variant 值对应关系。
完整示例
待补充：一个包含多参数类型和参数变体的完整自定义指令示例。
下一步
- 了解 Python 脚本开发 中事件监听与接口调用的详细方法
- 了解 自定义成就系统 中通过指令控制成就进度
- 查阅 ModSDK 文档中
CustomCommandTriggerServerEvent事件