跳到正文
本頁目錄

LeviLamina 模組 API:表單、數據包與網絡

LeviLamina 客戶端 mod 怎樣繪製自己的界面?有統一的 ImGui hook 嗎?

LeviLamina 沒有提供統一的 ImGui hook,也沒有對原版 JsonUI/OreUI 的封裝。維護者建議不要去 hook 系統層(DX/窗口)自己接 ImGui,而是直接接入 MC 自身的渲染/UI:LL 客戶端提供了 ll::event::BeforeUIRenderEvent / AfterUIRenderEvent(可拿到 ScreenView 和 MinecraftUIRenderContext),可在其中用 MC 的 UI 渲染上下文繪製;MC 的相關 API 都在 src-client/mc 頭文件中,可自行調用(JsonUI/OreUI 需自己實現,OreUI 因 Mojang 未開源部分庫較難做)。也可參考 Amethyst 等客戶端 mod 框架的例子。

注:LL 的 ll::form 以及新的 ll::ui(數據驅動 UI/DDUI 表單,見 data_driven_ui_guide)是服務端向玩家發送的表單 API,並非客戶端自繪界面的封裝。

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

LeviLamina 有沒有繪製線框(如顯示碰撞箱、領地範圍)的 API?能否像結構方塊那樣在客戶端顯示邊框?

LeviLamina 本身沒有調試圖形/線框 API,結構方塊的邊框是硬編碼的,不建議去摳。

服務端推薦使用 OEOTYAN 的 BedrockServerClientInterface(BSCI,https://github.com/OEOTYAN/BedrockServerClientInterface,也可在 https://levimc.org/mods/github.com/OEOTYAN/BedrockServerClientInterface/ 獲取)繪製調試圖形/線框,PLand 等領地插件的範圍顯示就是用它實現的。

若要在客戶端 mod 裡自己繪製,需要接入遊戲渲染:LL 客戶端的 BeforeUIRenderEvent / AfterUIRenderEvent 即基於 hook ScreenView::render 實現,可監聽這些事件或自行 hook 渲染函數。

適用版本:LeviLamina 26.x(BSCI 已發佈 v26.60.0 適配當前版本)

服務端 mod 如何給玩家發送只包含翻譯鍵(可帶參數)的文本,讓客戶端按自身語言翻譯顯示?自定義鍵名怎麼辦?

發送 Translate 類型的 TextPacket,例如:

cpp
TextPacket pkt{};
pkt.mLocalize = true;
pkt.mBody = TextPacketPayload::MessageAndParams{TextPacketType::Translate, "my.key", {"参数1", "参数2"}};
pkt.sendTo(player);

客戶端會用本地語言文件翻譯。原版鍵名可直接用;自定義鍵名則必須通過資源包把語言文件(texts/*.lang)下發給客戶端(服務器可用 resource_packs 強制下發),客戶端只能從資源包加載語言文件。無需用 BinaryStream 手寫包,協議格式可參考 Mojang 官方協議文檔。第三方前置(如 GMLIB)也提供了相關 API。

適用版本:當前 LeviLamina 版本(26.x)

LeviLamina 原生(C++)mod 如何自定義數據包,實現客戶端 mod 與服務端 mod 互相通信?

LeviLamina 自 1.9.0 起內置自定義數據包支持(ll/api/network)。當前寫法:

  • 繼承 ll::network::PacketBase<T> 並實現 write / read 定義數據包(繼承即註冊)。
  • 繼承 ll::network::PacketHandlerBase<Handler, Packet> 並實現 handlePacket(NetworkIdentifier const&, NetEventCallback&, ll::network::PacketSide side, Packet const&) 處理數據包。
  • 發送用 packet.sendToServer()(客戶端→服務端)、packet.sendTo(player) / sendToClient(networkId, subClientId) / sendToClients()(服務端→客戶端)。

需要在運行時動態註冊(例如腳本引擎)時使用 ll::network::PacketRegistrar::getInstance()。26.60 起還可聲明 CustomPacketId、PacketVersion、處理端 Side 以及 Optional,缺少必需數據包的一端會在登錄時被斷開。

適用版本:LeviLamina 1.9.0 及以上(handlePacket 簽名與 Side/Optional 為 26.60.0 及以上)

BDS 數據包(Packet)類的 write 函數是做什麼的?什麼時候會被調用?read 又是什麼?

write(BinaryStream&) 把數據包序列化寫入 BinaryStream,發送包時調用;read(ReadOnlyBinaryStream&) 則從 ReadOnlyBinaryStream 讀取數據,反序列化到 Packet 對象,接收包時調用(具體包類實現的是純虛函數 _read,read 內部調用它)。

ll::form::ModalForm 構造函數只接收標題、內容、兩個按鈕文本,回調放哪?按舊教程寫 lambda 報 No viable conversion ... to 'Callback' 怎麼辦?

回調在 sendTo(player, callback) 時傳入。ModalForm::Callback 的簽名為 void(Player&, ll::form::ModalFormResult, ll::form::FormCancelReason),其中 ModalFormResult = std::optional<ModalFormSelectedButton>,FormCancelReason = std::optional<ModalFormCancelReason>,後兩個參數都是 optional,需先判斷是否有值。最簡單寫法:form.sendTo(player, [](Player& player, ll::form::ModalFormResult result, ll::form::FormCancelReason reason) { ... });(也可用 auto)。參數類型寫錯(如直接寫 ModalFormSelectedButton 而非 optional)就會出現上述轉換錯誤。可參考官方表單指南 developer_guides/how_to_guides/form_guide。

適用版本:LeviLamina 0.11 及以上

LeviLamina C++ mod 中修改了玩家某個背包槽位的物品後,為什麼用發送 InventorySlotPacket 而不是調用 refreshInventory 來同步給客戶端?

Mob::refreshInventory() 會調用 sendInventory(true) 並 sendArmor 發送全部盔甲槽,即刷新整個背包和盔甲欄;而 InventorySlotPacket 只更新單個容器槽位(mInventoryId、mSlot、mItem),網絡數據量更小。只改一個物品時發 InventorySlotPacket 更合適。

另外 Actor::getPlayerOwner() 之類函數返回的是指針(Player*),可能為 nullptr(例如被強制生成的無主魚鉤),直接調用玩家函數會空指針崩服,應先判空。

LeviLamina C++ mod 中如何編寫表單(Form)?有沒有官方教程?

官方文檔有表單指南:https://levimc.org/zh-Hant/LeviLamina/developer_guides/how_to_guides/form_guide/(涵蓋 SimpleForm、ModalForm、CustomForm,通過 sendTo 發送並傳入回調),API 參考見 api_reference/form。也可以參考 LegacyScriptEngine 中表單 API 的實現代碼。

LeviLamina C++ 中發送 CustomForm(含 appendDropdown)給玩家,點提交正常,但玩家點右上角 X 關閉表單時服務器閃退,為什麼?

CustomForm 的回調簽名是 void(Player&, CustomFormResult const&, FormCancelReason),其中 CustomFormResult 是 std::optional<std::unordered_map<std::string, CustomFormElementResult>>。玩家點 X 關閉表單時結果為空(std::nullopt,且 FormCancelReason 有值),如果代碼直接 result->at("playerName") 或 std::get<std::string>(...) 訪問,就會訪問空 optional 或不存在的 key 而拋異常/崩潰。

正確做法是在回調中先判斷 if (!result) return;(或檢查 cancelReason),再用 find/contains 確認 key 存在、用 std::get_if 判斷類型後取值。另外 appendDropdown 的選項數組不要為空。

LeviLamina C++ 表單 CustomForm 中 appendStepSlider 的回調結果是什麼類型?

與 LSE 不同(LSE 返回序號),LeviLamina C++ 的 ll::form::CustomForm::appendStepSlider(name, text, std::vector<std::string> steps, defaultVal, tooltip) 在回調結果 CustomFormResult(std::unordered_map<std::string, CustomFormElementResult>)中對應的值是被選中那一項的字符串本身(std::string,存放在 std::variant<std::monostate, uint64, double, std::string> 裡),而不是索引。當前 v26.60.8 仍如此。

取值示例:

cpp
std::get<std::string>(result->at("name"))

適用版本:LeviLamina 0.11 及以上

LeviLamina 中的數據包(Packet)結構體是否完整,能否自己構造併發送數據包?

可以。LeviLamina 已補全了大量數據包結構體(mc/network/packet/ 下數百個頭文件),能滿足自行構造併發送數據包的需求;構造好後可用 LL 為 Packet 提供的發送方法,如 packet.sendTo(player)、sendTo(actor)、sendTo(pos, dimId)、sendToClients() 等。

LeviLamina 的 CustomForm 只能有一個提交按鈕嗎?能加其他按鈕嗎?

傳統表單 ll::form::CustomForm 只能通過 setSubmitButton(text) 設置一個提交按鈕,無法添加多個按鈕。需要多個按鈕或更復雜的交互時,可以使用基於 DDUI(數據驅動 UI)的新接口 ll::ui::CustomForm(頭文件 ll/api/ui/form/CustomForm.h),它支持 button(label, callback, options) 添加多個按鈕,以及 closeButton()、textField()、toggle()、dropdown() 等控件,並通過 show() / showAsync() 顯示。DDUI 接口需客戶端/BDS 支持數據驅動 UI。

適用版本:LeviLamina 26.60.x

LeviLamina(LL3)的 C++ API 裡還有 LL2 那樣發起 HTTP 請求的功能(httplib)嗎?

沒有。LeviLamina 不提供公開的 HTTP 請求封裝(ll/api/network 下只有 packet 相關內容)。需要自己在 xmake.lua 中引入第三方庫,例如 cpp-httplib(LegacyScriptEngine 就用 cpp-httplib 實現網絡請求,可參考其源碼)或 cpr,也可以基於 asio 自行實現。

適用版本:LeviLamina 所有版本(LL3 起)

在 LeviLamina C++ mod 中如何給某個玩家發送數據包?player->sendNetworkPacket 和 Packet::sendTo 有什麼區別?

構造好 Packet 後,可以調用 player.sendNetworkPacket(packet),也可以用 LeviLamina 提供的 packet.sendTo(player)。當前實現中 Packet::sendTo(Player const&) 會通過 Minecraft 的 PacketSender::sendToClient 按玩家的 NetworkIdentifier 和 SubClientId 發送,對普通在線玩家而言效果與 sendNetworkPacket 相同,只是更方便的封裝;另外還有 sendTo(BlockPos, DimensionType, except)、sendTo(Actor, except)、sendToClients() 等重載,用於按位置/實體廣播。

若發包後客戶端無反應,通常是包內容不正確被客戶端丟棄。

適用版本:當前所有 LeviLamina 版本

在 LeviLamina C++ 插件中,想強制關閉玩家當前打開的容器界面(箱子等),應該發什麼數據包?

發送 ContainerClosePacket,設置其載荷中的 mContainerId(玩家當前打開容器的 ID)並把 mServerInitiatedClose 設為 true,即可由服務端主動關閉玩家的容器界面。當前 ContainerClosePacket 繼承自 ll::PayloadPacket<ContainerClosePacketPayload>,字段 mContainerId / mContainerType / mServerInitiatedClose 定義在 ContainerClosePacketPayload 中。

注意:聊天欄、命令方塊編輯界面等並不都能這樣關閉;如果只是為了彈出表單,沒必要關閉所有界面。

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

在 LeviLamina mod 中如何構建併發送數據包?BinaryStream 的寫入順序看不懂怎麼辦?

推薦直接構造對應的 Packet 類(如 XxxPacket),給成員/payload 賦值後調用 sendTo(player) 等方法發送,而不是手寫 BinaryStream。

若一定要手寫 BinaryStream,按協議順序依次 write 字段即可;順序可參考 IDA 中對應 Packet::write 的實現、PowerNukkitX 的協議類,或帶註釋的 Go 協議庫 gophertunnel(github.com/Sandertv/gophertunnel/minecraft/protocol/packet)。Mojang 官方協議文檔不全且有錯誤。用 BinaryStream 發包的示例可參考 LegacyScriptEngine 的 src/legacy/api/PacketAPI.cpp。

注意不建議用 BDS 自帶的通用包類讀寫,部分包在 read/write 階段找不到來源會導致崩服。

適用版本:LeviLamina 當前版本

在 LeviLamina 原生(C++)mod 中如何顯示 BossBar?有沒有示例或文檔?

可以手動構造併發送 BossEventPacket(payload 為 BossEventPacketPayload,含 mEventType(BossEventUpdateType)、mName 等字段),類文檔見 https://lamina.levimc.org/api/dc/df0/classBossEventPacket.html。如果要讓某個生物顯示 boss 血條,不建議手動發包,應使用生物的 boss 組件實現;只有非生物的自定義 BossBar 才需要自己發包。

適用版本:LeviLamina 26.x

如何實現給玩家發送虛假世界種子(假種子)的插件?LSE 腳本似乎做不到。

需要原生 mod:hook StartGamePacket 的發送/構造相關函數,在發給客戶端之前修改其中的種子。在最新版本中,種子位於 StartGamePacketPayload::mSettings(LevelSettings)的 mSeed(LevelSeed64)。GMLIB 中有類似實現可參考。

適用版本:LeviLamina 當前版本

客戶端 mod 中如何獲取方塊的 3D 渲染圖(用於信息顯示類 mod)?

可以用 ItemRenderer(class ItemRenderer : public ActorRenderer)裡渲染方塊物品的函數,但在 HUD 上有些方塊可能顯示不出來(與渲染上下文和 hook 點有關);也有用戶建議直接用 BlockTessellator。

適用版本:LeviLamina 客戶端(src-client)mod。未能從源碼或文檔中直接證實,僅供參考。

想寫一個 LeviLamina mod,把服務器發給客戶端的特定數據包裡的文本自動翻譯成目標語言,應該怎麼實現?

hook 該數據包類的 write 函數(如 TextPacket::$write(BinaryStream&) const),在 hook 中修改這個數據包的成員(write 是 const,需要 const_cast;當前很多包是 ll::PayloadPacket<XxxPayload>,文本在 payload 成員裡,如 TextPacket 的 mBody),然後調用 origin 讓其繼續正常序列化發送。也可以改為在發送前攔截(如 iListenAttentively 的 SendPacketEvent)。

想發送假實體,AddActorPacket 怎麼構造?

不要直接調用構造函數湊字段(缺少實體數據等內部指針容易崩潰)。可參考 LSE 的做法:用 MinecraftPackets::createPacket(MinecraftPacketIds::AddActor) 創建包並 static_pointer_cast<AddActorPacket>,再填 mEntityId、mRuntimeId、mActorType、mPos 等字段後 sendTo(player)(見 LegacyScriptEngine/src/legacy/api/PlayerAPI.cpp 的 setBossBar 實現);或先創建一個臨時真實體,用 Actor::tryCreateAddActorPacket() 生成數據包,再修改包內座標等字段後發送。頭文件為 mc/network/packet/AddActorPacket.h。

適用版本:當前 LeviLamina 版本;當前 LegacyScriptEngine 版本

服務端能不能通過發包讓客戶端直接打開一本書查看內容?

基本做不到。查看書本是純客戶端行為,玩家翻看書時不會發包,只有修改內容時才會發 BookEditPacket;書的內容存在物品 NBT 裡。可以考慮變通方案,比如讓玩家打開一個放了這本書的講臺。

適用版本:BDS 原版協議行為,與 LeviLamina 版本無關。未能從源碼或文檔中直接證實,僅供參考。

通過發包對特定玩家隱藏其他玩家名字後,服務器過段時間會自動校正恢復,怎麼解決?

服務器本身會定期發 SetActorDataPacket 更新玩家實體元數據,與其單獨補發,不如在服務器發出該包時直接修改其中的 DataItem(SetActorDataPacketPayload::mPackedItems)。可參考開源插件 FuckNetherHeight 中的改包實現。

適用版本:LeviLamina 服務端,依賴 BDS 原版同步行為。未能從源碼或文檔中直接證實,僅供參考。