跳到正文
本頁目錄

LeviLamina 模組 API:命令

LeviLamina mod 卸載/禁用時,註冊的命令怎麼註銷?

不需要也無法手動註銷。BDS 命令不支持真正刪除,LeviLamina 也不提供註銷命令的 API;mod 被禁用時,LeviLamina 會自動禁用該 mod 註冊的命令重載(重新啟用後會恢復)。禁用後客戶端執行該命令會提示 Command version mismatch,這是預期行為。理論上可以過濾 AvailableCommandsPacket 讓客戶端不顯示,但 LeviLamina 本身不修改數據包。

適用版本:LeviLamina 0.12 及以上

LeviLamina C++ mod 中如何在後臺執行一條原版命令(如 tag),以服務器或玩家身份執行,並可選獲取命令輸出?

方式一(LeviLamina 封裝,可拿到輸出):#include "ll/api/command/CommandRegistrar.h",構造一個 CommandOrigin(如 ServerCommandOrigin 或 PlayerCommandOrigin),然後調用 CommandOutput out = ll::command::CommandRegistrar::getServerInstance().executeCommand("tag @a add foo", origin);,內部會先 compileCommand 再 run,結果在 CommandOutput 裡。

方式二(直接調 BDS,參考 LSE 的 mc.runcmd 實現):

cpp
CommandContext context(cmd, std::make_unique<ServerCommandOrigin>("Server", ll::service::getLevel()->asServer(), CommandPermissionLevel::Owner, 0), static_cast<int>(CurrentCmdVersion::Latest));
ll::service::getMinecraft()->mCommands->executeCommand(context, false);  // 第二个参数为 suppressOutput

以玩家身份執行時 origin 換成 std::make_unique<PlayerCommandOrigin>(level, player.getOrCreateUniqueID())。命令字符串不需要前導 /。需要捕獲輸出的寫法可參考 LSE 的 runcmdEx(compileCommand + command->run(origin, output))。相關頭文件:mc/world/Minecraft.h、mc/server/commands/MinecraftCommands.h、CommandContext.h、ServerCommandOrigin.h、PlayerCommandOrigin.h、CurrentCmdVersion.h。命令須在主線程執行。

適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)

LeviLamina 註冊命令時,可選參數(如座標 CommandPosition / CommandPositionFloat、字符串)怎麼聲明?怎麼判斷玩家是否填寫了該參數?

在參數結構體裡用 LeviLamina 提供的 ll::command::Optional<T>(頭文件 ll/api/command/Optional.h)包裝字段,並在 overload 中用 .optional("字段名") 聲明;執行時用 params.xxx.has_value()(或 if (params.xxx))判斷是否填寫,用 .value()/.get() 取值。例如:

cpp
struct Params { std::string name; ll::command::Optional<CommandPositionFloat> pos; };
cmd.overload<Params>().required("name").optional("pos").execute(...);

座標參數不要用 BlockPos,應使用 CommandPosition / CommandPositionFloat。獲取座標時應使用 origin.getExecutePosition(version, params.pos.value())(Optional 需先取值;version 為命令版本)(或 CommandPosition::getBlockPos(version, origin, offset)),而不是直接取原始座標,否則在 /execute 下得到的座標會錯誤。若需要完全不同的參數組合,也可以為命令註冊多個 overload(有該參數/無該參數各一個)。

適用版本:LeviLamina 26.60.x

開發 LeviLamina 客戶端 mod 時,按文檔寫法在 onEnable 中註冊命令不生效,客戶端/服務端命令該怎麼註冊?

命令分為客戶端命令和服務端命令:通過 ll::command::CommandRegistrar::getInstance(false)(或 getServerInstance())註冊服務端命令,getInstance(true)(或僅客戶端構建中存在的 getClientInstance())註冊客戶端命令。

客戶端在遊戲啟動完成(主界面出現)時就啟用所有 mod,此時還沒有命令註冊表,所以在 enable() 中註冊任何命令都不會成功。正確做法是:

  1. 監聽 ll::event::ServerCommandRegisterEvent,在回調中註冊服務端命令。
  2. 監聽 ll::event::ClientCommandRegisterEvent,在回調中註冊客戶端命令。

服務端(BDS)上 mod 在世界加載完成後啟用,可以直接在 enable() 中註冊,且 BDS 上只能註冊服務端命令;本地世界中兩者都可註冊,多人遊戲中只能註冊客戶端命令。

適用版本:LeviLamina 客戶端版 26.60.x

能否在 LeviLamina mod 中屏蔽/刪除某些已註冊的命令(例如原版 /me、/tell、/w、/msg)?

LeviLamina 沒有提供刪除命令的 API。原版命令可以通過 hook 攔截其註冊(setup)來去掉;但不要試圖去掉其他 mod 註冊的命令,強行這樣做容易導致崩服。

若只是為了防止玩家用目標選擇器(如 /me @e)刷屏/崩服,可以使用 LeviAntiCheat 的 disableSelector 配置禁止玩家在命令中使用目標選擇器。

適用版本:LeviLamina 當前版本(hook 方式依賴 BDS 實現)。未能從源碼或文檔中直接證實,僅供參考。

想用 LeviLamina 替換/擴展原版命令(如 stop、effect、tp 增加參數),需要先禁掉原版命令嗎?會衝突嗎?LSE 能做到嗎?

不需要禁掉原版命令(禁止原版命令的 setup 反而可能導致命令失效甚至 std::terminate)。用 LeviLamina 的 C++ 命令 API:ll::command::CommandRegistrar::getInstance(false).getOrCreateCommand("stop", ...)(或 getServerInstance())取得同名命令後用 .overload<Params>() 追加新的重載即可,與原版重載共存不衝突;也可以註冊新命令並通過 .alias(...) 設置別名。注意不要直接使用 StopCommand::mServer,它可能是空指針。

LSE(JS 插件)方面:舊的 NativeAPI 已被移除,但當前 LSE 的 mc.newCommand 內部同樣走 getOrCreateCommand,對已存在的命令名會提示 Runtime command ... already exists, changes will not be applied except for setOverload!,即描述/權限等不會改變,但通過 setOverload 仍可給該命令追加運行時重載。

適用版本:LeviLamina 當前版本

在 LeviLamina mod 中註冊/執行命令時需要的命令版本(command version)應該填多少?出現 Command version not matched 是怎麼回事?

執行/編譯命令時使用當前最新版本 CurrentCmdVersion::Latest(頭文件 mc/server/commands/CurrentCmdVersion.h),CommandRegistrar::executeCommand / compileCommand 的 version 參數默認就是它(getOrCreateCommand 註冊命令本身不需要填版本);在命令回調裡需要版本時(如 origin.getExecutePosition(version, pos))可直接使用命令實例自身的版本 cmd.mVersion,寫法參考 LeviLamina 源碼 src/ll/core/command/Teleport.cpp。

另外,原版對“命令版本不對”和“匹配不到正確的重載”兩種情況都會輸出 Command version not matched,因此看到該提示不一定是版本填錯,也可能是重載匹配失敗。BDS 26.32 適配初期曾有用戶遇到 LL 註冊的重載出現此提示,若遇到請先升級到最新版 LeviLamina 再排查。

適用版本:LeviLamina 26.60.x

BDS/LeviLamina 中註冊的命令名只能是小寫嗎?

是的,命令名應全部使用英文小寫字母(BDS 命令系統的限制)。LeviLamina 的 CommandRegistrar::getOrCreateCommand 直接把名字交給 BDS 的 CommandRegistry 註冊,不會替你轉換大小寫;枚舉值則會被 LL 自動轉小寫。

C++ 註冊命令時 CommandPermissionLevel 各等級(Any/GameDirectors/Admin/Host/Owner/Internal,0~5)分別對應什麼?OP 玩家是幾級?

這些枚舉名沿用 Mojang 原版:

  • 0 Any:普通成員。
  • 1 GameDirectors:BDS 默認給 OP 的等級,命令方塊也是這一級。
  • 2 Admin:比 1 高,但遊戲裡幾乎沒有命令用到。
  • 3 Host:完整 OP,相當於單人存檔房主的權限(如 /kick 需要 3 級)。
  • 4 Owner:控制台。
  • 5 Internal:供內部使用,與 4 基本沒有區別。

有用戶反饋:被 deop 的玩家即使在創造模式也用不了 GameDirectors 級命令;OP 能用 GameDirectors,但用不了 Admin/Host;控制台用不了 Internal 級。實際常用的是 0/1/3/4。在 server.properties 中加入 op-permission-level=4(注意鍵名帶 level)可以提高 OP 的等級,讓 OP 在遊戲內也能用 /stop 等命令。

適用版本:當前版本(權限行為取決於 BDS)。未能從源碼或文檔中直接證實,僅供參考。

LL 客戶端中,mod 同時在服務端和客戶端註冊了同名命令(如 /fm),玩家執行時以誰為準?客戶端命令應該在什麼時機註冊?

取決於註冊的是客戶端命令還是服務端命令:客戶端命令(CommandRegistrar::getClientInstance() / getInstance(true))會覆蓋服務端同名命令(典型例子是 help)。

當前版本 LeviLamina 已把命令註冊改為事件驅動:客戶端命令應在 ll::event::command::ClientCommandRegisterEvent 中註冊,服務端命令在 ServerCommandRegisterEvent 中註冊(LL 自帶的 BuiltinCommands 就是這樣做的,每次觸發時先 registrar.clear() 再重新註冊),這樣退出重進世界、進入其它服務器時命令都會被正確重建。舊的做法(在 ClientJoinLevelEvent 或 onEnable 裡註冊、或把 client side 設為 false 繞過)已不需要。

適用版本:LeviLamina 26.10.0 及以上(客戶端版)

LeviLamina 原生命令中拿到座標參數後如何得到真實座標?直接調用 CommandPosition::getPosition 有什麼問題?

使用 origin.getExecutePosition(cmd.mVersion, param.pos) 直接得到 Vec3 座標(需要整數時再轉 BlockPos),無需自己處理相對座標 offset。getExecutePosition 內部會調用 CommandPosition::getPosition,而 /execute 上下文的 CommandOrigin 重寫了該函數,所以自己直接調 getPosition 在 /execute 下得到的座標會錯誤。命令版本請傳 Command::mVersion。

注意當前 getExecutePosition 的參數類型是 CommandPositionFloat const&,因此參數結構體裡的座標字段建議聲明為 CommandPositionFloat。可參考 LeviLamina 源碼 src/ll/core/command/Teleport.cpp 的寫法。

適用版本:LeviLamina 0.11 及以上

LeviLamina 命令 overload 中,座標(Vec3)類型的命令參數應該用什麼類型?

在參數結構體中使用 CommandPositionFloat(或 CommandPosition,CommandPositionFloat 繼承自 CommandPosition)。由於 CommandOrigin::getExecutePosition 接收 CommandPositionFloat,推薦用 CommandPositionFloat。參數類型名沿用 Mojang 的命名,沒有統一前綴,可在 mcwiki 查命令參數類型名稱,或參考 LeviLamina 的 src/ll/core/command/Teleport.cpp。

適用版本:LeviLamina 0.11 及以上

LeviLamina 命令註冊(CommandRegistrar / overload)中的 .text() 和 .postfix() 分別有什麼作用,怎麼用?

text 是在命令里加一個固定的字面量文本(關鍵字),例如 /aa bb cc 可寫成 cmd.overload().text("bb").text("cc").execute(...);它與 std::string 類型參數不是一回事。

postfix 是給它前面的那個參數加後綴(把上一個參數設為後綴參數,原版只支持整數後綴)。例如:xp.overload<XP>().required("value")... 與 xp.overload<XP>().required("level").postfix("l")...,則 /xp 1 匹配第一個重載,/xp 2l 匹配第二個重載。

適用版本:LeviLamina 0.11 及以上

LeviLamina 註冊命令時 command.overload().execute([](CommandOrigin const& origin, CommandOutput& output){...}) 中的 origin 和 output 分別是什麼?logger 必須從入口類獲取嗎?

origin(CommandOrigin)是命令執行來源,可通過 getEntity()、getName()、getOriginType() 等得知是誰執行的命令;output(CommandOutput)用於返回命令執行結果,如 output.success("...") / output.error("...")(支持 fmt 格式化)。

logger 不必從入口 mod 獲取:ll::io::Logger 不能直接構造,可用 ll::io::LoggerRegistry::getInstance().getOrCreate("名字") 得到一個 std::shared_ptr<Logger> 全局使用;只在開發時需要的日誌可用 debug 級別。

適用版本:LeviLamina 1.x 及以上

LeviLamina 註冊命令時,參數枚舉只能逐個寫死嗎?想用可動態變化的枚舉值(傳數組)該怎麼做?

使用軟枚舉(soft enum)。軟枚舉的值可以在運行時動態增刪,典型例子是原版 scoreboard 命令的 objectives 參數。在 LL 中可用 ll::command::CommandRegistrar::getInstance(false).tryRegisterSoftEnum("名字", {值...}) 註冊,之後用 addSoftEnumValues / removeSoftEnumValues / setSoftEnumValues 動態修改;參數類型可用 ll::command::SoftEnum<T>(ll/api/command/SoftEnum.h)。

適用版本:LeviLamina 1.x 及以上

LeviLamina 註冊的自定義命令是否支持像原版 /tp 那樣同一個命令字面量後接不同類型參數(如目標選擇器或座標)執行不同邏輯?

支持。通過 CommandRegistrar::getOrCreateCommand 得到 CommandHandle 後,多次調用 overload<Params>() 註冊多個重載即可,每個重載有自己的參數列表和 execute 回調。

注意重載之間的匹配優先級:例如同一位置同時註冊了 <字符串> 參數的重載和 <枚举> 參數的重載,解析時會始終走字符串那個重載,因此設計重載時要避免字符串參數吞掉其它類型。

適用版本:LeviLamina 1.x 及以上

在 LeviLamina mod 中如何讓目標選擇器(@a、@p 等)選不中某些玩家(如隱身玩家)?

可以 hook CommandSelectorBase::newResults(返回 std::shared_ptr<std::vector<Actor*>>),在原函數結果中過濾掉不想被選中的玩家;這樣目標選擇器就無法選中這些玩家(如隱身玩家)。

適用版本:LeviLamina 0.13.x 及以上(當前版本仍有該函數)

在 LeviLamina 原生 mod 中註冊命令時,物品、方塊、效果等類型的參數(對應舊 LLSE 的 ParamType.Item/Block/Effect)該用什麼類型?

不要參考 LL2 的實現,去看 LeviLamina 源碼 src/ll/api/command/runtime/ParamKind.h,其中 ParamKind::Kind 枚舉列出了運行時命令支持的所有參數類型,包括 Item、BlockName、BlockState、Effect、ActorType、Actor、Player、BlockPos、Vec3、JsonValue、FilePath 等,ParamKindList 給出對應的 C++ 類型(如 Effect 對應 MobEffect const*)。

適用版本:LeviLamina 0.11 及以上

在 LeviLamina 命令回調 lambda 裡使用 mod 的 logger 報錯(this 未捕獲 / 未找到匹配的重載函數),應該怎麼在命令回調中輸出信息?

命令回調裡應使用回調參數中的 CommandOutput(output.success(...) / output.error(...),支持 fmt 格式化)向執行者輸出,而不是用 logger。如果確實要用 logger,不要捕獲 this,直接在 lambda 內通過 mod 單例獲取,如 my_mod::MyMod::getInstance().getSelf().getLogger().info(...)。

適用版本:LeviLamina 0.11 及以上

開發 LeviLamina mod 時,在哪裡能找到註冊 MC 命令等功能的示例代碼?

首先看官方文檔的開發者指南:命令註冊見“命令指南”(developer_guides/how_to_guides/command_guide,使用 ll/api/command/CommandRegistrar.h 的 CommandRegistrar::getInstance(false).getOrCreateCommand(...),再 command.overload<Params>().required(...).execute(...)),此外還有事件、表單、hook、i18n 等指南,以及 LeviLamina 倉庫 src-test 下的測試代碼(如 src-test/server/testCommand.cpp)。另外大部分 LeviLamina mod 都發布在 lip 包索引上,可以找一個同類 mod 打開其源碼倉庫作參考。

適用版本:LeviLamina 1.x 及以上

mod 註冊命令別名時,能佔用其他 mod(甚至 LeviLamina 自帶命令)的別名,這是 bug 嗎?

別名是通過 CommandHandle::alias() 註冊的,底層調用 BDS 的 CommandRegistry::registerAlias。LeviLamina 只會用 findCommand 檢查這個名字是否已經是一個命令:已存在就靜默跳過、不註冊;但別名和別名之間的衝突,要看 BDS 原版 registerAlias 的行為(可能後註冊的覆蓋先註冊的),LeviLamina 不負責。寫 mod 時請自己避免和已有的命令或別名重名。

適用版本:當前 LeviLamina 版本。未能從源碼或文檔中直接證實,僅供參考。

mod 註冊的命令,怎樣才能讓沒有管理員權限的玩家看不到(不出現在命令補全裡)?

註冊時給命令設置更高的權限等級,例如 ll::command::CommandRegistrar::getInstance(false).getOrCreateCommand("mycmd", "描述", CommandPermissionLevel::GameDirectors)(或 Admin、Host 等更高等級)。權限不夠的玩家既看不到也執行不了這個命令。默認值 CommandPermissionLevel::Any 表示所有人都能看到。

適用版本:當前 LeviLamina 版本

用 LeviLamina C++ 註冊一個名為 whitelist 的自定義命令後不生效/衝突,為什麼?

BDS 原版的 whitelist 命令(allowlist 的別名)仍然存在、沒有被刪除,自定義同名命令會與之衝突,應換一個命令名。另外原版白名單命令是 4 級(控制台)權限命令。

適用版本:LeviLamina 服務端(BDS),取決於原版 BDS 命令表。未能從源碼或文檔中直接證實,僅供參考。

用 LeviLamina 給原版命令(如 gamemode)追加一個重載後直接崩潰或報錯,怎麼正確給原版命令加重載?runtime overload 是不是可以隨時加的重載?

問題在於註冊時間點:命令重載必須在該命令註冊後緊跟著添加(註冊了 a、再註冊 b 之後就不能再改 a),否則原版命令會壞一片。正確做法是 hook 對應命令的 setup,在原命令重載註冊完之後添加(若 setup 被內聯,可改為在下一個命令註冊前添加)。runtimeOverload()(RuntimeOverload)指沒有編譯期參數類型檢查、在運行時動態描述參數的重載,而不是可以隨時添加的重載。

適用版本:LeviLamina 1.x 及以上

LeviLamina 命令重載如何設置執行回調?execute<fn>() 寫法還能用嗎?

不能。自 0.12 起 execute<fn>()(模板參數傳回調)已改為 execute(fn)(普通參數傳回調),其他用法不變。例如:

cpp
cmd.overload<Params>().required("name").execute([](CommandOrigin const& origin, CommandOutput& output, Params const& params) { ... });

適用版本:LeviLamina 0.12 及以上