跳到正文
本頁目錄

🎯 命令相關 API

下面這些API提供了在遊戲中註冊、監聽自定義命令的接口

執行一條後臺命令

mc.runcmd(cmd)

  • 參數:
    • cmd : String
      待執行的命令
  • 返回值:是否執行成功
  • 返回值類型: Boolean

[JavaScript]

JavaScript
mc.runcmd("say Hello!");

[Lua]

Lua
mc.runcmd("say Hello!")

執行一條後臺命令(強化版)

mc.runcmdEx(cmd)

  • 參數:

    • cmd : String
      待執行的命令
  • 返回值:命令執行結果Object

  • 返回值類型: Object<Boolean,String>

    • 對於返回的某個執行結果對象res,有如下這些成員:
成員 含義 類型
res.success 是否執行成功 Boolean
res.output BDS執行命令後的輸出結果 String

Note

runcmdEx 與普通 runcmd 實現區別非常大,在於 Ex 版本擁有隱藏輸出的機制,執行結果不會輸出至控制台,因此如果有需要,要手動用 log 函數將結果輸出

[JavaScript]

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

命令註冊 API

這裡提供了註冊自定義命令的接口。通過對接 BDS 內置的命令系統,你註冊的命令可以由玩家、控制台、命令方塊、NPC等各種遊戲中可以執行命令的對象所使用,在 addon 中,也可以使用這裡所註冊的命令。

Warning

命令中除了可變參數(String, RawText, Message等)外,均不能包含非英文小寫字母!

註冊一條頂層命令

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

  • 參數:
    • cmd : String
      待註冊的命令
    • description : String
      命令描述文本
    • permission : PermType (可選參數)指令執行所需權限
    • flag : Integer
      (可選參數)默認值 0x80
      目前直接按此輸入即可,後續會進行相關修改
    • alias : String
      (可選參數)命令的別名
      可以為命令設置多個別名,執行的時候相當於觸發同一條命令
執行權限 含義
PermType.Any 任何人都可以執行這條指令
PermType.GameMasters 只有OP可以執行這條指令(默認值)
PermType.Console 只有控制台可以執行這條指令
  • 返回值:指令對象
  • 返回值類型:Command

Tip

頂層命令,也就是類似 list gamerule 這種,在 / 之後第一個輸入的部分

註冊完頂層命令後,此函數會返回一個指令對象。接下來,對於這個命令的功能擴展都需要在這個指令對象中進行

指令對象 - 函數

通過指令對象,你可以為這個命令註冊各式各樣的形式、功能。假設有一個叫 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

有效的命令參數類型及解釋

命令參數類型 含義
ParamType.Bool 布爾值參數
ParamType.Int 整數參數
ParamType.Float 浮點數參數
ParamType.Dimension 維度參數
ParamType.String 字符串參數
ParamType.Actor 實體目標選擇器參數
ParamType.Player 玩家目標選擇器參數
ParamType.BlockPos 整數座標參數
ParamType.Vec3 浮點數座標參數
ParamType.RawText 原始字符串參數(可包含特殊字符,如逗號空格,只能作為最後一個參數使用)
ParamType.Message 消息類型參數(同 /say 指令參數,會自動展開目標選擇器等)
ParamType.JsonValue JSON字符串參數
ParamType.Item 物品類型參數
ParamType.Block 方塊類型參數
ParamType.Effect 效果類型參數
ParamType.Enum 枚舉參數
ParamType.SoftEnum 可變枚舉參數
ParamType.ActorType 實體類型參數
ParamType.Command 指令名稱參數(僅供測試)

新增一條指令重載

要想讓命令正常運行,必須至少添加一條重載。所謂重載,本質上相當於參數的組合,譬如重載['a', 'b', 'c']相當於命令可以被執行為 /cmd <a> <b> <c>,而重載[]相當於可以被執行為/cmd。重載的參數標識符可以是參數名、枚舉名、參數標識符,但不能使用無法區分具體參數的標識符,如兩個參數都叫 action 但枚舉選項不同,此時應該使用枚舉名而不是參數名。

Command.overload(params)

  • 參數:
    • params : Array<String>
      參數標識符,重載所用到的參數列表,可用 參數標識符、枚舉名、參數名。
      注意不能使用無法區分具體參數的標識符,如兩個參數都叫 action 但枚舉選項不同,此時應該使用枚舉名而不是參數名
  • 返回值:是否成功設置
  • 返回值類型:Boolean

Tip

指令重載是 BDS 區分不同指令形式的方法,每一種不同的指令形式對應著一種指令重載。
如你所見,指令重載中提供的各項參數名組成了一種新的指令形式

設置指令回調

Command.setCallback(callback)

  • 參數:
    • callback : Function(cmd,origin,output,results)
      註冊的這個命令被執行時,接口自動調用的回調函數。
  • 返回值:是否成功設置
  • 返回值類型:Boolean

Tip

指令回調函數的參數相對複雜,在下面將進行詳細解釋

安裝指令

在對命令的所有配置完成之後,使用此函數將命令註冊到 BDS 的命令系統當中

Command.setup()

  • 返回值:是否成功安裝
  • 返回值類型:Boolean

指令回調函數

上文提到的 指令回調函數 是一個比較複雜的回調函數,下面對其中的各項參數進行一些解釋
指令回調函數原型: Function(cmd,origin,output,results)

參數 cmd : 自身的指令對象

這個參數給出了你註冊這個命令時使用的指令對象。

參數 origin :命令的執行者

參數 origin的類型為 CommandOrigin 對象。此對象表示此次命令的執行者,通過這個對象,可以對執行者進行一些操作
對於某個特定的 CommandOrigin 對象ori,有以下這些屬性

屬性 含義 類型
ori.type 指令執行主體類型 OriginType
ori.name 指令執行主體的名稱 String
ori.pos 指令執行主體的座標 FloatPos
ori.blockPos 指令執行主體的方塊座標 IntPos
ori.entity 執行指令的實體(可空) Entity
ori.player 執行指令的玩家(可空) Player

參數 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值,而数据值 即為執行者在當前命令參數的位置填上的內容

命令參數類型 和 數據值類型 的對應關係如下

命令參數類型 數據值類型 含義
ParamType.Bool Boolean 布爾值
ParamType.Int Integer 整數
ParamType.Float Float 浮點數
ParamType.Dimension Integer 維度 ID
ParamType.String String 字符串
ParamType.Actor Array<Actor> 實體目標選擇器 選中的實體
ParamType.Player Array<Player> 玩家目標選擇器 選中的實體
ParamType.BlockPos IntPos 整數座標對象
ParamType.Vec3 FloatPos 浮點數座標對象
ParamType.RawText String 原始字符串(可包含特殊字符,如逗號空格,只能作為最後一個參數使用)
ParamType.Message String 消息類型字符串(同 /say 指令參數,會自動展開目標選擇器等)
ParamType.JsonValue String JSON字符串
ParamType.Item Item 物品類型
ParamType.Block Block 方塊類型
ParamType.Effect String 效果類型字符串
ParamType.Enum String 枚舉字符串
ParamType.SoftEnum String 可變枚舉字符串
ParamType.ActorType String 實體類型字符串
ParamType.Command String 指令名稱(僅供測試)

命令註冊樣例

[JavaScript]

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

Warning

儘管看起來比較簡單,但是假命令有一些很重要的缺點,包括只能由玩家或控制台執行,其他對象(如命令方塊、NPC等)都無法執行、所有參數數據都需要自行解析等等。

請儘量使用 真命令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]

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]

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

假命令註冊相關說明

設置了回調函數之後,在你註冊的這個假命令被執行的時候,回調函數就會被調用。
在調用之前,腳本引擎會自動幫你把命令參數分割成數組。
以JavaScript語言為例: 執行命令
mc.regPlayerCmd("land buy", "购买领地", function(pl,args){ .... }, 0 );
之後,
當你使用命令 /land buy abcde 12345的時候,這個回調函數就會被調用。
回調函數的參數args被傳入一個數組:[ "abcde" , "12345" ]
正如所見,args 中包含的值是被 按順序分割好的 命令參數。
如果你的命令中有引號(比如說為了處理含有空格的玩家名字),腳本引擎在分割時也會做處理。

其他與命令系統有關的 API

模擬產生一個控制台命令輸出

mc.sendCmdOutput(output)

  • 參數:

    • output : String
      模擬產生的命令輸出
  • 返回值:是否成功執行

  • 返回值類型:Boolean