---
front: https://nie.res.netease.com/r/pic/20220408/3e2bb79b-32b3-4b95-a408-83556c00f775.jpg
hard: 入门
time: 20分钟
selection: true
---
# 自定义指令
## 概述
开发者可以通过在行为包中配置json来添加自定义指令。添加的自定义指令支持在聊天栏预览和Tab补全，支持与指令相关的所有事件及接口。
## 注册
以demo [CustomCommandDemo](../13-模组SDK编程/60-Demo示例.md#CustomCommandDemo)为例。
1. 在behavior中新建`netease_commands`目录。
2. 在目录下新建一个json，编写指令的定义。json文件命名推荐为`团队名_模组命名空间_指令名称`，例如`craftStudio_customCommandDemo_explode`，文件名应使用英文数字和下划线，不可含有中文和特殊字符。
3. 打开json文件编写指令定义，以demo中的customtest2指令为例，文件位于`netease_commands/craftStudio_customCommandDemo_customtest2.json`。
```json
{
"format_version": "0.0.1",
"name": "customtest2",
"description": "测试所有配置默认值的参数",
"permission_level": "game_directors",
"args": [
{"name": "浮点数", "type": "float", "default": 12.3},
{"name": "整数", "type": "int", "default": 12},
{"name": "字符串", "type": "str", "default": "hello"},
{"name": "目标", "type": "target", "default": "@s"},
{"name": "位置", "type": "pos", "default": [2.5, 3.0, 4.4]},
{
"name": "实体",
"type": "entity",
"default": {"entityType": "minecraft:sheep"}
},{
"name": "物品",
"type": "item",
"default": {"itemName": "minecraft:apple"}
}
]
}
```
- 以下是代码和说明。
|键|类型|解释|
|:-|:-|:-|
|format_version|str|格式版本，请填写0.0.1|
|name|str|指令名称，例如gamemode|
|description|str|指令描述，支持在语言文件（例如zh_CN.lang）中定义|
|permission_level|str|权限等级，可选game_directors、admin、host、owner、any，具体含义如下
game_directors：任何操作员都可以运行此命令，包括命令方块
admin：任何操作员都可以运行此命令，但命令方块不能
host：任何服务器主机都可以运行此命令
owner：只有专用服务器可以运行此命令
any：任何人都可以运行此命令|
- args是一个包含object的列表，定义指令的参数。每个object都代表一个参数，object的顺序决定指令参数的输入顺序，每个object的参数说明如下
|键|类型|解释|
|:-|:-|:-|
|name|str|参数名称，会在输入提示中显示|
|type|str|参数类型，目前仅支持上面json里的7种类型参数|
|default|any|参数默认值，可填写任意json数据格式|
- 例如配置为`{"name": "浮点数", "type": "float"}`时，输入时会显示
- default不必和type的类型符合，**含有default的参数必须排在参数列表的尾部**，且在游戏中可以不传。
例如配置为`{"name": "浮点数", "type": "float", "default": null}`时，输入时会显示
## 使用
- 开发者需要监听CustomCommandTriggerServerEvent，为自定义指令编写功能。
- 使用SetCommand接口可以触发自定义指令。
- 使用GlobalCommandServerEvent可以监听所有指令，包括自定义指令。
## demo说明
- customCommandDemo实现了三个指令，`customtest`和`customtest2`指令用来给开发者测试各种参数的用法，`explode`指令实现了让指定坐标或实体位置发生爆炸的功能。
- 通过编写两个json文件，注册两次explode，可实现可变参数类型功能，但需要注意这种情况下，你只能根据参数的value去判断，name和type将失效。例如，如果你注册了`/explode `和`/explode `，那么玩家调用/explode 1 1 1 1将无法解析。通常情况下不建议重复注册指令，除非你明确知道自己要做什么。
- 该指令支持多种调用方式，示例如下
```
让发送指令的对象爆炸
/explode
让发送对象的上方8格爆炸
/explode ~~8~
让所有鸡爆炸
/explode @e[type=chicken]
让发送对象的上方8格爆炸，爆炸范围为3，不破坏方块，不产生火焰
/explode ~~8~ 3 0
让发送对象爆炸，爆炸范围为3，破坏方块，产生火焰
/explode @s 3 1 1
```