註冊命令
插件可以向遊戲添加命令。玩家在 / 後輸入它們,有正常的補全和提示;控制台、命令方塊和 NPC 也可以運行它們。
本指南註冊一個帶參數、權限和回調的命令,然後介紹 LLSE 的簡單命令。
示例使用 JavaScript;API 在每種語言中都相同。這裡用到的每個函數都可以在命令相關 API 中查到。
1. 創建命令
在入口腳本的頂層創建命令,或像參考文檔那樣放在 onServerStarted 監聽器中:服務器仍在啟動時,LSE 會把註冊推遲到可以註冊命令時,
所以兩種寫法都可以。本指南使用監聽器:
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 添加可以省略的參數:
cmd.mandatory("target", ParamType.Player);
cmd.optional("message", ParamType.RawText);ParamType.Player 接受玩家名或目標選擇器,例如 @a。ParamType.RawText 接受這一行剩下的全部內容,包括空格;
它只能作為最後一個參數。參數類型列表給出了每種類型以及回調為它得到的值。
3. 聲明命令的形式
重載是命令的一種形式:按順序排列的參數列表:
cmd.overload(["target", "message"]);有了這個重載,/hello Steve、/hello Steve Nice to see you! 和 /hello @a Welcome! 都是有效的。命令有多種形式時,
為每種形式聲明一個重載,例如 /hello <target> [message] 和 /hello all。
4. 處理命令
每次命令被運行時都會調用回調。它得到命令本身、來源(誰或什麼運行了它)、輸出(把結果寫到哪裡)以及按名稱給出的參數值:
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() 把命令註冊到遊戲中。完整的插件:
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 類型的參數,並在重載中寫上枚舉名。這是參考中的示例:
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 用一次調用註冊命令及其函數,並把命令後面的詞作為字符串數組傳入:
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 還會返回命令的輸出,且不會把它寫到控制台:
const result = mc.runcmdEx("list");
log(result.output);