跳到正文
本頁目錄

註冊命令

插件可以向遊戲添加命令。玩家在 / 後輸入它們,有正常的補全和提示;控制台、命令方塊和 NPC 也可以運行它們。 本指南註冊一個帶參數、權限和回調的命令,然後介紹 LLSE 的簡單命令。

示例使用 JavaScript;API 在每種語言中都相同。這裡用到的每個函數都可以在命令相關 API 中查到。

1. 創建命令

在入口腳本的頂層創建命令,或像參考文檔那樣放在 onServerStarted 監聽器中:服務器仍在啟動時,LSE 會把註冊推遲到可以註冊命令時, 所以兩種寫法都可以。本指南使用監聽器:

JavaScript
mc.listen("onServerStarted", () => {
    const cmd = mc.newCommand("hello", "Says hello to players", PermType.Any);
    // 参数、重载和回调:第 2 到 4 步
    cmd.setup();
});

mc.newCommand(name, description, permission) 創建命令並返回一個命令對象,接下來對它進行配置。命令名只能使用英文小寫字母。 權限決定誰可以運行它:

權限 誰可以運行命令
PermType.Any 任何人。
PermType.GameMasters OP。
PermType.Admin 管理員權限等級(默認值)。
PermType.Console 僅控制台。

cmd.setAlias("hi") 為同一個命令添加另一個名字。

2. 添加參數

每個參數都有名稱和類型。mandatory 添加必須給出的參數,optional 添加可以省略的參數:

JavaScript
cmd.mandatory("target", ParamType.Player);
cmd.optional("message", ParamType.RawText);

ParamType.Player 接受玩家名或目標選擇器,例如 @a。ParamType.RawText 接受這一行剩下的全部內容,包括空格; 它只能作為最後一個參數。參數類型列表給出了每種類型以及回調為它得到的值。

3. 聲明命令的形式

重載是命令的一種形式:按順序排列的參數列表:

JavaScript
cmd.overload(["target", "message"]);

有了這個重載,/hello Steve、/hello Steve Nice to see you! 和 /hello @a Welcome! 都是有效的。命令有多種形式時, 為每種形式聲明一個重載,例如 /hello <target> [message] 和 /hello all。

4. 處理命令

每次命令被運行時都會調用回調。它得到命令本身、來源(誰或什麼運行了它)、輸出(把結果寫到哪裡)以及按名稱給出的參數值:

JavaScript
cmd.setCallback((_cmd, origin, output, results) => {
    const from = origin.player ? origin.player.name : "The server";
    for (const player of results.target) {
        player.tell(`${from} says: ${results.message ?? "Hello!"}`);
    }
    output.success(`Said hello to ${results.target.length} player(s).`);
});
  • origin.player 是運行命令的玩家;由控制台或命令方塊運行時為 Null。
  • results.target 是一個玩家數組:一個選擇器可以匹配多個玩家。
  • 省略了可選參數時,results.message 沒有值。
  • output.success(msg) 向運行命令者顯示結果;output.error(msg) 顯示錯誤。

然後 cmd.setup() 把命令註冊到遊戲中。完整的插件:

JavaScript
mc.listen("onServerStarted", () => {
    const cmd = mc.newCommand("hello", "Says hello to players", PermType.Any);
    cmd.mandatory("target", ParamType.Player);
    cmd.optional("message", ParamType.RawText);
    cmd.overload(["target", "message"]);
    cmd.setCallback((_cmd, origin, output, results) => {
        const from = origin.player ? origin.player.name : "The server";
        for (const player of results.target) {
            player.tell(`${from} says: ${results.message ?? "Hello!"}`);
        }
        output.success(`Said hello to ${results.target.length} player(s).`);
    });
    cmd.setup();
});

重啟服務器,在遊戲中輸入 /hello @a,或在控制台中輸入 hello @a。

用枚舉實現子命令

對於 /manager add <name> 和 /manager list 這樣的命令,使用枚舉:一組固定的詞。用 setEnum 給每組詞起一個名字, 為它添加一個 ParamType.Enum 類型的參數,並在重載中寫上枚舉名。這是參考中的示例:

JavaScript
mc.listen("onServerStarted", () => {
    let 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();
});

兩個枚舉參數都叫 action,所以回調從 res.action 讀取所選的詞;重載寫的是枚舉名,由它們區分兩者。對於服務器運行時會變化的一組詞 (玩家名、家的名字),使用軟枚舉:setSoftEnum、addSoftEnumValues 和 ParamType.SoftEnum。

LLSE 的簡單命令

mc.regPlayerCmd 和 mc.regConsoleCmd 用一次調用註冊命令及其函數,並把命令後面的詞作為字符串數組傳入:

JavaScript
mc.regPlayerCmd("ping", "Answers with pong", (player, args) => {
    player.tell("Pong!");
});

mc.regConsoleCmd("backup", "Starts a backup", (args) => {
    log(`Starting backup ${args[0] ?? "default"}.`);
});

保留它們是為了為 LLSE 編寫的插件。只有玩家(regPlayerCmd)或控制台(regConsoleCmd)能運行它們,命令方塊和 NPC 不能, 參數也要你自己解析。新插件請使用 mc.newCommand。

在插件中運行命令

mc.runcmd("say Hello!") 在後臺運行一個命令,並返回是否成功。mc.runcmdEx 還會返回命令的輸出,且不會把它寫到控制台:

JavaScript
const result = mc.runcmdEx("list");
log(result.output);