LegacyScriptEngine API:命令
LSE JS 插件用 mc.newCommand 註冊命令報錯或不生效(舊 LLSE 插件遷移過來也一樣),正確寫法是什麼?必須放在 onServerStarted 裡嗎?
現在不需要把命令註冊放進 onServerStarted。LSE 0.6.0 起支持延遲註冊命令:服務器還在啟動時調用 mc.newCommand / mc.regPlayerCmd,LSE 會自動推遲到可以註冊的時候再執行,所以直接寫在插件頂層即可,放在 onServerStarted 回調裡也同樣能用。早期 LSE(0.6.0 之前)強制要求在 onServerStarted 之後註冊,這個限制已經取消。
正確寫法參考文檔 https://lse.levimc.org/zh/apis/GameAPI/Command/:先創建命令對象,再添加重載、設置回調,最後調用 setup()。該寫法適用於當前 LSE 0.23.x:
const cmd = mc.newCommand("ping", "网络诊断", PermType.Any);
cmd.overload([]);
cmd.setCallback((_cmd, ori, out, res) => {
const p = ori.player;
if (!p) return;
const d = p.getDevice();
p.tell(`延迟: ${d.lastPing}ms 丢包: ${d.lastPacketLoss.toFixed(1)}%`);
});
cmd.setup();注意事項:
- 每條命令至少要添加一條重載,無參數命令寫
cmd.overload([])(當前實現中cmd.overload()不帶參數效果相同)。 - 按文檔在最後調用
cmd.setup()(當前實現裡實際註冊已在overload時完成,setup()主要為兼容保留,但仍建議照文檔書寫)。 - 命令名含大寫字母或非英文字符:除 String/RawText/Message 等可變參數外,命令中只能用英文小寫字母。
- flag 參數可省略,默認值就是
0x80(文檔要求按此填寫即可);不要照搬 AI 生成的其他寫法。
適用版本:LSE 0.6.0 及以上
基岩版玩家名可以帶空格,LSE 插件用 mc.runcmd 拼接命令時出錯,怎麼處理?如何阻止名字帶空格的玩家進服?
根本做法是拼接命令時用雙引號把玩家名包起來,例如 mc.runcmd("say \"" + player.name + "\" test") 或模板字符串 mc.runcmd(`say "${player.name}" test`)(mc.runcmdEx 同理);第三方插件出此問題應讓作者修復。若臨時要拒絕名字帶空格的玩家,可寫一個 JS 插件:
mc.listen("onPreJoin", (pl) => {
if (pl.realName.includes(" ")) pl.kick();
});適用版本:當前所有 LSE 版本
LSE 中用 mc.newCommand 註冊命令後,在 setCallback 回調裡如何拿到執行命令的玩家對象?直接用 player.name 會報錯。
命令回調的簽名是 (cmd, origin, output, results),參數裡沒有 Player,執行者信息在 origin(CommandOrigin)裡:用 origin.player 獲取執行命令的玩家對象,例如 origin.player.name。注意 origin.player 可能為空(例如控制台或命令方塊執行時),使用前應先判空。
適用版本:LegacyScriptEngine 當前所有版本
LSE 中不同插件註冊命令時使用了同名的枚舉(cmd.setEnum),會衝突嗎?例如插件更新後子命令枚舉值被別的插件覆蓋(rank give 變成 rank add)。
會。LSE 的 cmd.setEnum 註冊的是 BDS 全局的運行時枚舉,名稱不按插件/命令區分命名空間。兩個插件使用同名但取值不同的枚舉時會互相覆蓋,導致命令解析錯亂。解決辦法:插件開發者給枚舉起全局唯一的名字(如在枚舉名前加插件名前綴)。維護者表示在 LSE 層面修復需要重做命令註冊 API、會不兼容舊插件,因此不會改;原生 C++ mod 的命令有命名空間,不存在此問題。
適用版本:LegacyScriptEngine 當前所有版本
LSE 中 mc.runcmd 會每個 tick 自動執行一次嗎?想每 tick 執行命令該怎麼寫?
不會,mc.runcmd 調用時隻立即執行一次。若要每 tick 執行,可監聽 onTick 事件:mc.listen("onTick", () => { mc.runcmd("...") });若需要固定時間間隔則用 setInterval(fn, 毫秒)。
適用版本:LegacyScriptEngine 當前所有版本(原為 LLSE)
LSE 插件中 mc.runcmdEx 執行的命令如果語法錯誤,會影響插件運行嗎?
不會讓插件出錯或崩潰。命令編譯失敗時 runcmdEx 仍正常返回結果對象,其中 success 為 false,output 中是錯誤信息,可據此判斷:
const res = mc.runcmdEx(cmd);
if (!res.success) logger.warn(res.output);適用版本:LegacyScriptEngine 當前版本
LSE 腳本插件裡執行命令時,如何隱藏控制台輸出的命令執行反饋?
使用 mc.runcmdEx 代替 mc.runcmd。runcmdEx 有隱藏輸出機制,執行結果不會打印到控制台,而是作為返回值 {success, output} 返回;如需要可自行用 log/logger 輸出 res.output。
適用版本:LegacyScriptEngine 當前版本
LSE 插件執行命令時,怎麼用 OP/控制台權限執行?怎麼拿到命令輸出?
mc.runcmd(cmd) 以服務器控制台身份(ServerCommandOrigin,權限等級 Owner,高於 OP)執行命令,不受玩家權限限制,只返回是否成功(Boolean)。mc.runcmdEx(cmd) 同樣以控制台身份執行,並返回 {success, output} 對象,可把 output 存進變量分析,且不會把輸出打印到控制台。
LSE 中 mc.runcmd 和 mc.runcmdEx 有什麼區別?
mc.runcmd(cmd) 執行一條後臺命令,只返回是否成功(Boolean),命令輸出會正常打到控制台;mc.runcmdEx(cmd) 執行命令並返回結果對象 { success: Boolean, output: String },且輸出被隱藏、不會顯示在控制台,需要時自行 log(result.output)。
注意不要在 onConsoleCmd 監聽裡調用 runcmd/runcmdEx,否則可能死循環。
LSE 中 mc.runcmdEx 執行命令的權限等級是多少?
與控制台相同:mc.runcmd / mc.runcmdEx 都以名為 "Server" 的 ServerCommandOrigin 執行,權限等級為 CommandPermissionLevel::Owner(最高級),所以能執行控制台可執行的所有命令。
LSE 中寫跨服傳送,用 mc.listen("onPlayerCmd") 監聽玩家輸入(假命令)好,還是註冊真命令?怎麼註冊?
建議註冊真命令,客戶端有命令提示,命令方塊等處也能用。示例:
mc.listen('onServerStarted', () => {
const cmd = mc.newCommand('trans', '跨服命令', PermType.Any);
cmd.mandatory('ip', ParamType.String);
cmd.optional('port', ParamType.Int);
cmd.optional('player', ParamType.Player);
cmd.overload(['ip', 'port', 'player']);
cmd.setCallback((_, origin, output, result) => {
const players = result.player ?? (origin.player ? [origin.player] : []);
players.forEach(p => p.transServer(result.ip, result.port ?? 19132));
});
if (!cmd.setup()) logger.error('命令安装失败!');
});注意 setup() 成功返回 true,失敗判斷要取反;從控制台執行且未指定 player 時 origin.player 為空。
LSE 中如何觸發/調用數據包(行為包)裡的 mcfunction 函數,而不用把它重寫一遍?
通過執行原版 function 命令即可:mc.runcmdEx("function 函数名")(以控制台身份執行,返回 {success, output}),或 pl.runcmd("function 函数名")(以玩家身份執行)。
在 LSE 中用 mc.newCommand 註冊命令,調用 cmd.optional(...) 加了可選參數後,遊戲裡有命令提示,執行時卻提示 未知的命令,為什麼?另外文檔裡 pl.tell(msg[,type]) 的中括號是什麼意思?
文檔裡的 [ ] 只是表示“可選參數”的寫法,不是讓你用數組把參數包起來,調用時按順序直接傳參即可,例如 hub.optional("hub_num", ParamType.Int)。
命令顯示未知是因為沒調用 overload:加完參數後必須用 cmd.overload([...]) 聲明重載(例如 hub.overload(["hub_num"]),無參重載可寫 hub.overload([])),然後 setCallback,最後 setup()。
參考 https://lse.levimc.org/zh/apis/ 和 https://github.com/LiteLDev/legacy-script-engine-api。
適用版本:LSE 0.23.x
LSE 有沒有獲取服務器所有已註冊命令列表的 API?
LSE 沒有提供獲取全部已註冊命令列表的現成 API(命令相關接口只有 mc.runcmd / mc.runcmdEx / mc.newCommand / mc.regPlayerCmd / mc.regConsoleCmd / mc.sendCmdOutput 等)。
變通做法是用 mc.runcmdEx("help") 執行 help 命令,再解析返回的 output 文本。如確實需要完整列表,可用 C++ 模組通過 LeviLamina / BDS 的 CommandRegistry 獲取。
適用版本:LSE 當前所有版本(0.23.1 仍無此 API)
LSE 有沒有讓某個實體執行一條命令的 API?實體對象上沒有類似 execute 的方法。
LSE 的實體(Entity)對象沒有執行命令的方法(只有玩家對象有 pl.runcmd)。可以藉助原版 execute 命令實現:用 mc.runcmdEx 執行 execute as @e[c=1,type=<实体类型>] at @s run <命令>(按需加上座標 / 名稱 / 標籤等選擇器條件來精確定位實體,例如先給目標實體加 tag 再用 @e[tag=xxx])。
若用 C++,可參考 LSE 源碼中命令執行相關實現。
適用版本:LSE 當前所有版本
LSE 註冊命令後,在回調裡用 out.success(...) 輸出信息,但玩家執行命令後客戶端看不到任何結果,怎麼辦?
排查思路:
- 先在回調裡
log(res.action)等確認參數是否正確傳入、回調是否被執行; switch的每個case末尾要寫break,否則會繼續往下執行導致輸出被覆蓋或出錯;- 確認世界的
sendcommandfeedback遊戲規則沒有被關閉; - 作為變通,可以用
ori.player.tell(...)直接給執行者發消息(注意控制台執行時ori.player為空)。
另外,使用 KVDatabase 等數據庫用完記得 close,否則其他地方再次打開會報錯。
適用版本:LSE 當前所有版本。未能從源碼或文檔中直接證實,僅供參考。
LSE 註冊命令時使用玩家選擇器參數,回調裡直接取 res.pl.name 得到 undefined,為什麼?
ParamType.Player(以及 ParamType.Actor)參數返回的是對象數組(Array<Player> / Array<Actor>),而不是單個對象,需要按下標取,例如 res.pl[0].name,或遍歷數組處理(注意先判斷數組長度,選擇器可能沒選中任何玩家)。
適用版本:LSE 當前所有版本
LSE 註冊命令時怎麼給一個命令設置多個別名?
多次調用 cmd.setAlias(alias) 即可,每調用一次添加一個別名。C++ 側對應 LeviLamina 的 CommandHandle::alias(),其內部調用 CommandRegistry::registerAlias。
適用版本:LSE 當前所有版本
LSE 註冊命令時,怎樣實現像原版 tag 命令那樣參數是字符串但能 Tab 補全已有值?把參數改成 SoftEnum 後遊戲裡沒有提示怎麼辦?
使用可變枚舉(軟枚舉):先用 cmd.setSoftEnum(name, values) 定義可變枚舉及其初始值,再用 cmd.mandatory / cmd.optional(參數名, ParamType.SoftEnum, name)聲明參數並加入重載;之後可用 cmd.addSoftEnumValues / removeSoftEnumValues 動態增刪可選值。只有可變枚舉裡有值時,遊戲內才會出現補全提示。
LSE 註冊的命令(如 /home)執行時提示權限不足,怎麼解決?
常見原因是命令沒有設置重載。用 mc.newCommand 創建命令後,必須至少添加一條重載,例如無參命令調用 cmd.overload([]),再 setCallback 並 setup。另外要注意 mc.newCommand 的 permission 參數默認是 PermType.Admin,若希望普通玩家可用需顯式傳 PermType.Any,例如 mc.newCommand("home", "回家", PermType.Any)。
LSE 的命令來源類型 OriginType 中為什麼沒有 Server,只有 DedicatedServer 等?
LSE 運行時的 OriginType 枚舉是直接由 BDS 原版的 CommandOriginType 生成的,成員名與原版一致:Player、CommandBlock、MinecartCommandBlock、DevConsole、Test、AutomationPlayer、ClientAutomation、DedicatedServer(7)、Entity、Virtual、GameArgument、EntityServer、Precompiled、GameDirectorEntityServer、Scripting、ExecuteContext。控制台/服務端來源應使用 OriginType.DedicatedServer。legacy-script-engine-api 的 TS 聲明沿用了 LL2 時代的名字(Server、Block、Actor 等,並把 DedicatedServer 作為 Server 的別名),所以編輯器補全會出現 Server,但運行時並不存在該成員;也可用 ori.typeName 獲取類型名字符串。
LSE 的命令註冊 API 裡有方塊狀態(block states)類型的命令參數嗎?能取到值嗎?
ParamType 枚舉裡保留了 BlockState(數值為 16),可以用於 mandatory / optional 註冊參數,但 LSE 在把命令解析結果轉換成腳本值時沒有處理該類型,回調裡拿到的該參數值為空(undefined),因此實際上無法使用。需要方塊狀態時可改用字符串/JSON 等參數自行解析。
適用版本:LSE v0.23.1
LSE 腳本中如何讓玩家身份執行命令?player.runcmd 能否執行管理員(OP)命令?
LSE 提供 player.runcmd(cmd) 以玩家身份執行命令。其底層用該玩家構造 PlayerCommandOrigin 執行,與玩家自己輸入命令沒有區別,所以能執行哪些命令取決於該玩家的權限,非 OP 玩家不能借此執行管理員命令。若需要以高權限執行,可用控制台身份 mc.runcmd / mc.runcmdEx(ServerCommandOrigin,Owner 權限)配合 /execute as "<玩家名>" run <命令> 實現。
LSE 菜單類插件(如 cmenu)點按鈕執行命令時提示“未知的命令”,是什麼原因?
這類插件一般用 pl.runcmd() 以玩家身份、按玩家權限執行命令。玩家權限不夠(命令要求 OP),或者提供該命令的插件(領地、商店、簽到等)沒裝、命令沒註冊時,都會提示未知命令。解決方法:先裝好提供這些命令的插件,例如領地用 iland,商店用 pshop 或 Tmessential;然後在菜單的 JSON 配置裡刪掉不需要的條目。改 JSON 時注意語法,最後一個元素後面不能有多餘的逗號。
適用版本:當前版本(具體取決於所用第三方菜單插件和命令插件)。未能從源碼或文檔中直接證實,僅供參考。
LSE/LLSE 中 Command 對象的 setSoftEnum() 和 setEnum() 有什麼區別?
setSoftEnum(name, values) 註冊的是可變枚舉(soft enum),配合 ParamType.SoftEnum 參數使用,命令註冊後候選值仍可以用 addSoftEnumValues / removeSoftEnumValues 等動態修改。setEnum(name, values) 註冊的是普通枚舉,註冊後不能再改。需要在運行時變動候選項(如玩家名、動態列表)時用軟枚舉。
修改了 LSE 插件中命令的權限等級後重載插件仍不生效,為什麼?
LSE 的命令在 mc.newCommand 首次註冊時就確定了名稱、描述、權限等信息。重載插件時命令已存在,LSE 會警告 Runtime command xxx already exists, changes will not beapplied except for setOverload!(源碼原文如此),只有重載/回調會更新,權限等改動需要重啟服務器才生效。另外注意權限枚舉:PermType.Any(0) < PermType.GameMasters(1,OP) < PermType.Admin(2,mc.newCommand 默認值) < PermType.HostPlayer(3) < PermType.Console(4);Admin 比 GameMasters 高一級。不想限制權限可用 PermType.Any,並在回調裡自行判斷(如 origin.player?.isOP())。LSE 本身沒有提供註冊後修改命令權限的接口。
適用版本:LSE 0.9 及以上;當前 0.23.x
在 LSE 插件裡想限制某些玩家使用其他插件的指令,攔截指令後其他插件的表單仍然彈出,能否攔截其他插件的表單?
正常情況下在 onPlayerCmd 中返回 false 攔截命令執行,就能阻止其他插件的命令(及其後續表單),除非對方插件的“指令”是通過監聽聊天等事件而非註冊命令實現的。LSE 技術上也能攔截表單,但不建議這樣做;正確做法是攔截命令執行,或讓插件之間直接聯動禁止執行。
在 LSE 腳本插件中用 mc.runcmdEx("list") 獲取在線玩家列表時,返回結果裡帶有 § 顏色代碼,導致解析/顯示異常,怎麼處理?
mc.runcmdEx 返回的是對象 {success, output},命令輸出在 .output 字段中,需要自己去除顏色代碼,例如:
mc.runcmdEx("list").output.replace(/§./g, "")如果只是想拿在線玩家,更推薦直接用 mc.getOnlinePlayers() 獲取玩家對象數組再自行統計,避免解析本地化的命令輸出文本。
如何用 LSE 寫一個 /back 命令讓玩家返回上次死亡點?需要自己記錄死亡座標嗎?
不需要自己記錄。LSE 的玩家對象提供 pl.lastDeathPos 屬性(IntPos,包含維度 dimid);玩家沒有死亡記錄時,該屬性為空(undefined)。示例:
const cmd = mc.newCommand('back', '返回死亡点', PermType.Any);
cmd.overload([]);
cmd.setCallback((cmd, origin, output, result) => {
const player = origin.player;
if (!player) return output.error('指令执行者必须为玩家');
const pos = player.lastDeathPos;
if (!pos) return output.error('没有死亡记录');
player.teleport(pos);
output.success('传送成功');
});
cmd.setup();注意:ScriptX 取不到值時返回 undefined 而不是 null,判空應寫 !x,不要寫 == null 的嚴格比較。另一種做法是讀取 player.getNbt() 中原版的死亡座標字段,但字段名屬於 BDS 原版結構,不如直接用 lastDeathPos 可靠。
用 LSE 註冊命令時(例如 /pay <玩家> <金额>),如何讓某個參數可選,不填也不會被客戶端標紅報錯?
命令語法檢查在客戶端完成。註冊參數時用 cmd.optional(name, type, ...) 代替 cmd.mandatory(...) 聲明該參數,或者額外提供一個不包含該參數的重載(cmd.overload([...]) 中不列該參數),然後在回調裡判斷 results 中該參數是否為空/undefined。
適用版本:LSE 當前所有版本
用 LSE 註冊自定義命令(mc.newCommand)需要注意什麼?
- 命令名(及除
String/RawText/Message等可變參數外的內容)只能用英文小寫字母。 RawText類型參數只能放在最後一個參數位置。- 推薦在
onServerStarted事件中註冊命令(官方示例即如此)。 overload的參數是數組,無參數時寫cmd.overload([]);最後必須調用cmd.setup()。
示例(Python):
cmd = mc.newCommand(name, description, permission)
cmd.overload([])
def callback(cmd_, origin_, output_, results_): pass
cmd.setCallback(callback)
cmd.setup()具體見 LSE 文檔 GameAPI/Command。
適用版本:LSE 當前所有版本