🎯 命令相關 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