🎯 命令相关 API

下面这些API提供了在游戏中注册、监听自定义命令的接口

执行一条后台命令

mc.runcmd(cmd)

• 参数：
  • cmd : String
    待执行的命令
• 返回值：是否执行成功
• 返回值类型： Boolean

[JavaScript]

mc.runcmd("say Hello!");

[Lua]

mc.runcmd("say Hello!")

执行一条后台命令（强化版）

mc.runcmdEx(cmd)

• 参数：

  • cmd : String
    待执行的命令

• 返回值：命令执行结果Object

• 返回值类型： Object<Boolean,String>

  • 对于返回的某个执行结果对象res，有如下这些成员：

[JavaScript]

var result = mc.runcmdEx("say Hello!");
log(result.output);

命令注册 API

这里提供了注册自定义命令的接口。通过对接 BDS 内置的命令系统，你注册的命令可以由玩家、控制台、命令方块、NPC等各种游戏中可以执行命令的对象所使用，在 addon 中，也可以使用这里所注册的命令。

注册一条顶层命令

mc.newCommand(cmd,description[,permission,flag,alias])

• 参数：
  • cmd : String
    待注册的命令
  • description : String
    命令描述文本
  • permission : PermType （可选参数）指令执行所需权限
  • flag : Integer
    （可选参数）默认值 0x80
    目前直接按此输入即可，后续会进行相关修改
  • alias : String
    （可选参数）命令的别名
    可以为命令设置多个别名，执行的时候相当于触发同一条命令

• 返回值：指令对象
• 返回值类型：Command

指令对象 - 函数

通过指令对象，你可以为这个命令注册各式各样的形式、功能。假设有一个叫 Command的指令对象，则有下面这些成员函数

设置指令别名

Command.setAlias(alias)

• 参数：
  • alias : String
    指令别名
• 返回值：是否成功设置
• 返回值类型：Boolean

新增一个指令枚举选项

Command.setEnum(name,values)

• 参数：
  • name : String
    枚举名，用于设置参数时区分枚举
  • values : Array<String>
    枚举的有效值
• 返回值：新增枚举选项的标识名称
• 返回值类型：String

新增一个必选参数

Command.mandatory(name,type[,enumName,identifier,enumOptions])

• 参数：
  • name : String
    参数名，用于执行指令时识别参数
  • type : ParamType
    命令参数类型
  • enumName : String
    枚举名（仅 ParamType 为 Enum 时有效，用于区分枚举选项）
  • identifier : String
    参数标识，特殊情况下用于唯一识别参数，一般可用 enumName 或 name 代替
  • enumOptions : Integer
    参数选项，设置为 1 可在指令提示中展开枚举选项
    如 <action : TagChangeAction> 会变成 <add|remove>
• 返回值：是否成功设置
• 返回值类型：Boolean

新增一个可选参数

Command.optional(name,type[,enumName,identifier,enumOptions])

• 参数：
  • name : String
    参数名，用于执行指令时识别参数
  • type : ParamType
    命令参数类型
  • enumName : String
    枚举名（仅 ParamType 为 Enum 时有效，用于区分枚举选项）
  • identifier : String
    参数标识，特殊情况下用于唯一识别参数，一般可用 enumName 或 name 代替
  • enumOptions : Integer
    参数选项，设置为 1 可在指令提示中展开枚举选项
    如 <action : TagChangeAction> 会变成 <add|remove>
• 返回值：是否成功设置
• 返回值类型：Boolean

有效的命令参数类型及解释

新增一条指令重载

要想让命令正常运行，必须至少添加一条重载。所谓重载，本质上相当于参数的组合，譬如重载['a', 'b', 'c']相当于命令可以被执行为 /cmd <a> <b> <c>，而重载[]相当于可以被执行为/cmd。重载的参数标识符可以是参数名、枚举名、参数标识符，但不能使用无法区分具体参数的标识符，如两个参数都叫 action 但枚举选项不同，此时应该使用枚举名而不是参数名。

Command.overload(params)

• 参数：
  • params : Array<String>
    参数标识符，重载所用到的参数列表，可用 参数标识符、枚举名、参数名。
    注意不能使用无法区分具体参数的标识符，如两个参数都叫 action 但枚举选项不同，此时应该使用枚举名而不是参数名
• 返回值：是否成功设置
• 返回值类型：Boolean

设置指令回调

Command.setCallback(callback)

• 参数：
  • callback : Function(cmd,origin,output,results)
    注册的这个命令被执行时，接口自动调用的回调函数。
• 返回值：是否成功设置
• 返回值类型：Boolean

安装指令

在对命令的所有配置完成之后，使用此函数将命令注册到 BDS 的命令系统当中

Command.setup()

• 返回值：是否成功安装
• 返回值类型：Boolean

指令回调函数

上文提到的 指令回调函数 是一个比较复杂的回调函数，下面对其中的各项参数进行一些解释
指令回调函数原型： Function(cmd,origin,output,results)

参数 cmd ： 自身的指令对象

这个参数给出了你注册这个命令时使用的指令对象。

参数 origin ：命令的执行者

参数 origin的类型为 CommandOrigin 对象。此对象表示此次命令的执行者，通过这个对象，可以对执行者进行一些操作
对于某个特定的 CommandOrigin 对象ori，有以下这些属性

参数 output ：向命令执行者输出命令的执行结果

参数output的类型为CommandOutput 对象。通过这个对象，可以向命令执行者输出命令的执行结果。
对于某个特定的 CommandOutput 对象outp，有以下这些成员方法

输出一条成功信息

outp.success([msg][, parm])

• 参数：
  • msg : String
    要输出的信息
  • parm : Array 要替换的参数
• 返回值：是否成功输出
• 返回值类型：Boolean

输出一条错误信息

outp.error(msg[, parm])

• 参数：
  • msg : String
    要输出的信息
  • parm : Array 要替换的参数
• 返回值：是否成功输出
• 返回值类型：Boolean

输出一条普通信息

outp.addMessage(msg[, parm])

• 参数：
  • msg : String
    要输出的信息
  • parm : Array 要替换的参数
• 返回值：是否成功输出
• 返回值类型：Boolean

参数 result ：命令各项参数获取的结果

results 的内容为 object<命令参数名-数据值> 键值对。其中 命令参数名 为命令注册时设置的参数的 name值，而数据值 即为执行者在当前命令参数的位置填上的内容

命令参数类型 和 数据值类型 的对应关系如下

命令注册样例

[JavaScript]

mc.listen("onServerStarted", () => {
    const cmd = mc.newCommand("manager", "Command Description", PermType.GameMasters);
    cmd.setAlias("mgr");
    cmd.setEnum("ChangeAction", ["add", "remove"]);
    cmd.setEnum("ListAction", ["list"]);
    cmd.mandatory("action", ParamType.Enum, "ChangeAction", 1);
    cmd.mandatory("action", ParamType.Enum, "ListAction", 1);
    cmd.mandatory("name", ParamType.RawText);
    cmd.overload(["ChangeAction", "name"]);
    cmd.overload(["ListAction"]);
    cmd.setCallback((_cmd, _ori, out, res) => {
        switch (res.action) {
            case "add":
                return out.success(`add "${res.name}"`);
            case "remove":
                return out.success(`remove "${res.name}"`);
            case "list":
                return out.success(`Name List:`);
        }
    });
    cmd.setup();
});

假命令 API

这里的假命令API为 向下兼容 而留存，推荐使用上面文档所写的的 真命令 API

注册一个新的玩家命令（假命令）

mc.regPlayerCmd(cmd,description,callback[,level])

• 参数：
  • cmd : String
    待注册的命令
  • description : String
    命令描述文本
  • callback : Function(player,args)
    注册的这个命令被执行时，接口自动调用的回调函数。
  • level : Integer
    （可选参数）命令的注册等级，默认为 0 ，即所有人都可以执行
    如果设置命令注册等级为1，则只有OP可以执行此命令
• 返回值：是否成功注册
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(player,args)

• player : Player
  执行命令的玩家对象
• args : Array<String,String...>
  目标命令后面的参数。按空格为分界分割，组成字符串数组。
  如注册了自定义命令 land set，当执行 /land set abc 2333 时，args的值将为 [ "abc","2333" ]

[JavaScript]

mc.regPlayerCmd("fly on", "Turn on the fly mode", function (pl, args) {
    pl.tell("Flying enabled.");
    //......
});

注册一个新的控制台命令（假命令）

mc.regConsoleCmd(cmd,description,callback)

• 参数：

  • cmd : String
    待注册的命令

  • description : String
    命令描述文本

  • callback : Function
    注册的这个命令被执行时，接口自动调用的回调函数。

• 返回值：是否成功注册
• 返回值类型：Boolean

注：参数callback的回调函数原型：function(args)

• args : Array<String,String...>
  目标命令后面的参数。按空格为分界分割，组成字符串数组。
  如注册了自定义命令 land set，当执行 /land set abc 2333 时，args的值将为 ['abc','2333']

[JavaScript]

mc.regConsoleCmd("backup", "Start the backup", function (args) {
    log("ID of this backup is:", args[0]);
    //......
});

其他与命令系统有关的 API

模拟产生一个控制台命令输出

mc.sendCmdOutput(output)

• 参数：

  • output : String
    模拟产生的命令输出

• 返回值：是否成功执行

• 返回值类型：Boolean