開發 LeviLamina 模組:綜合問題
服務端命令和客戶端命令的區別
- 服務端命令是指由服務端註冊的命令,可以被服務端自己以及其它處於同一服務端的玩家執行。
- 客戶端命令完全由客戶端自行處理,只能由客戶端自身執行,其它玩家和服務端不知道客戶端命令的存在。
當LeviLamina運行在Bedrock Dedicated Server(下文簡稱BDS)上時,模組只可註冊服務端命令。
當Minecraft處於本地世界時,本質上就是在Minecraft內部運行了一個BDS,這時既可以註冊服務端命令也可以註冊客戶端命令。
當Minecraft處於多人遊戲中時,模組只能註冊客戶端命令。
可以通過
ll::command::CommandRegistrar::getInstance(false); // 服务端
ll::command::CommandRegistrar::getInstance(true); // 客户端獲取服務端和客戶端的CommandRegistrar來註冊命令。
在模組的enable()方法中註冊命令,服務端(BDS)成功客戶端失敗
因為服務端(BDS)和客戶端啟用所有模組的時機是有區別的。
- 服務端會在服務器初始化完成(世界已經加載完成)時啟用所有模組
- 客戶端會在遊戲啟動完成(主界面窗口出現)時啟用所有模組
所以在客戶端上,在enable()方法中註冊命令不會成功,無論是客戶端命令還是服務端命令,
解決方案就是監聽ServerCommandRegisterEvent然後再註冊服務端命令,監聽ClientCommandRegisterEvent然後再註冊客戶端命令。
模組調用MCAPI(比如Player::disconnect())時,出現ACCESS VIOLATION異常
請檢查調用MCAPI的代碼是否運行在MC_SERVER線程上,絕大多數服務端側的MCAPI只能在MC_SERVER線程中調用,這是Minecraft的遊戲設計限制。
LeviLamina 有沒有類似 Bukkit Javadoc 那樣的 C++ API 文檔?Minecraft 本身的類有文檔嗎?
有。由頭文件自動生成的 Doxygen C++ 參考在 https://levimc.org/LeviLamina/api/;帶說明和示例的 LeviLamina API 參考在 https://levimc.org/zh-Hant/LeviLamina/api_reference/。Minecraft 原版類(mc/ 下的頭文件)沒有官方文檔,需要自行閱讀頭文件。LSE 的腳本 API 文檔是手寫的,形式不同。
能否用 LeviLamina native mod 註冊自定義物品、方塊、實體/生物?LL 有現成接口嗎?
可以,但 LeviLamina 沒有提供高層的物品/方塊/生物註冊封裝,它主要把 MC 自身的函數暴露出來,需要像原版那樣自己走註冊流程。物品可手動構造並註冊,例如:
SharedPtr<Item> item = SharedPtr<Item>::make("my_mod:managed_item", ++registry->mMaxItemID);
registry->registerItem(item);(ItemRegistry::registerItem、Item(std::string const&, short) 構造均為 MCAPI,有用戶在 1.9.2 實測可行。)方塊可參考 LL 已實現的 BlockDefinitionGroup::registerDataDrivenBlock。只要註冊正確,客戶端一般沒問題,不提供資源包也不會出錯(只是沒有材質),需要顯示紋理時配合資源包。
添加生物/實體建議直接用原版 addon(行為包+資源包),純服務端即可實現;addon 做不到的功能才需要自己逆向原版實現並通過 hook/調用 MC 函數完成。
適用版本:LeviLamina 當前版本(26.60.x),服務端
BDS 官方提供的 PDB 裡有結構體信息和 RTTI 嗎?
沒有。一般 PDB 包含符號表、結構體、RTTI 等信息,但 BDS 發佈的 PDB 剔除了結構體和 RTTI,只保留了符號表,結構體佈局需要逆向獲得。LeviLamina 頭文件中大量 mUnkxxxx(::ll::UntypedStorage<对齐, 大小>)成員就是因為佈局靠逆向得出、成員名未知。
適用版本:當前 BDS 發佈版。未能從源碼或文檔中直接證實,僅供參考。
GitHub 上的 OEOTYAN/BedrockServerClientInterface 是做什麼的?
它是 bsci 庫,用於服務端在客戶端上繪製幾何圖形(線、盒子、圓、球等),作為舊 ParticleAPI 的替代。用法:
- 在
xmake.lua中添加add_repositories("OTOTYAN https://github.com/OEOTYAN/xmake-repo.git")和add_requires("bsci")。 #include <bsci/GeometryGroup.h>。- 用
bsci::GeometryGroup::createDefault()創建後調用line/box/circle/sphere繪製,用remove移除。
適用版本:當前版本(項目仍在維護)
LeviLamina 的 native(原生)模組、LSE 插件和 addon 有什麼區別?想開發應該學什麼?
native 模組用 C++ 基於 LeviLamina 編寫,直接 hook BDS,能力接近 Java 版的 Fabric 模組,因此稱為“模組”;用 JS/Lua/Python 通過 LegacyScriptEngine(LSE)編寫的稱為“插件”,入門簡單但功能受限於 LSE 提供的 API;addon(行為包/資源包及 Script API)是 Minecraft 官方自帶的擴展方式,原版 BDS 只能用 addon/SAPI。C++ 寫不好容易導致崩服,新手可先從 LSE 的 JS 入手。
只在自己客戶端裝了 LeviLamina 模組,進入別人的服務器還能用嗎?
取決於模組怎麼開發、用到了哪些函數:LeviLamina 的 MC 頭文件分為服務端專用、客戶端專用和雙端共用部分。只要模組在聯機時不依賴服務端專用函數(即純客戶端模組)就可以在進服時使用;例如某些回放類客戶端模組雖然也 hook 了服務端函數,但進服時不會走到那些代碼,所以仍可在服務器裡使用。注意“僅安裝在客戶端”的模組不等於“純客戶端”模組。
適用版本:LeviLamina 客戶端版(經 LeviLauncher 加載)
是否任何編譯型語言(如 Kotlin/Native、易語言)編譯出的 dll 都可以直接作為 LeviLamina 插件?
不行。LeviLamina 的 API 是 C++(大量模板),其他語言需要通過 C FFI 互操作,並需要一層類似 LegacyScriptEngine 的兼容層來提供 API 和事件;而 LL 的模板代碼很難用 C 封裝,最多隻能封裝 MC 部分。目前沒有方便的非 C++ native 方案。若想用非 C++ 語言開發,建議使用 LSE(JS/Lua/Python/NodeJS)。
能否在 BDS(LeviLamina)上添加自定義附魔(新的附魔效果)?行為包或修改 NBT 附魔 id 能實現嗎?
附魔是硬編碼的,不支持用行為包添加;把 NBT 中附魔 id 改成非原版編號也不會被識別。只能用 native(C++ mod)實現,而且僅在服務端註冊新附魔客戶端不會認,還要自行處理收發包,並自己實現鐵砧和附魔臺的 GUI。第三方庫 GMLib 中帶“允許非原版”選項的接口只是給物品添加原版附魔、允許超過最大附魔等級,並非自定義附魔。
適用版本:當前所有版本(取決於 BDS 原版實現)。未能從源碼或文檔中直接證實,僅供參考。
通過 LeviLauncher 使用的客戶端 mod 能用什麼語言開發?LeviLamina 客戶端有相機等客戶端類的頭文件嗎?
客戶端 mod 用 C++ 基於 LeviLamina(client)開發。當前 LeviLamina 已包含大量客戶端相關類,例如 src/mc/client/camera/、src-client/mc/client/game/ClientInstance.h、src-client/mc/client/gui/controls/renderers/HudCameraRenderer.h 等,常用客戶端類基本已覆蓋。
適用版本:LeviLamina 客戶端版(2026 年 3 月之後的版本)
開發 LeviLamina mod 時想用的 MC 函數在頭文件裡被標記為 MCNAPI(not public/未導出),編譯鏈接時報缺符號或 deprecated,怎麼辦?
LeviLamina 出於 Mojang 方面的安全要求採用符號白名單,只開放已有 mod 用到的符號(26.60 起進一步縮減,必須精確到每個符號,不再整類加白;成員變量未刪)。頭文件中 MCNAPI 標記的函數會提示“This API is not available. Open an issue if you need it.”。解決辦法:到 https://github.com/LiteLDev/mcapi-requests 開 issue,把編譯/鏈接階段缺失的函數(符號)列表直接貼進去,並附上 mod 倉庫或下載鏈接證明確實在寫 LL mod(主要用於攔截寫外掛的人),正當用途都會通過;申請內容簡短即可,不要用 AI 生成長篇文案。在新版本導出之前,只能自行用特徵碼(signature scan)、指針偏移、寫死 RVA 等方式定位,虛函數可從虛表獲取。另外注意 BlockSource 不應被拷貝,應使用引用,例如 auto& region = ...getDimensionBlockSource();。
適用版本:LeviLamina 1.4 及以上,尤其 26.60.x
LeviLamina 新版本(適配新 BDS)還沒正式發佈時,C++ mod 開發者怎樣提前適配?
把 mod 項目 xmake.lua 裡 levilamina 依賴的版本寫成 LeviLamina 主分支(main)最新的完整 40 位 commit hash(短 hash 會被 xmake 當成分支名而拉取失敗),例如 add_requires("levilamina <40位commit-hash>", {configs = {target_type = get_config("target_type")}}),也可直接寫分支名 levilamina main,即可基於開發中的頭文件開始適配;此時 xmake 會提示 Unknown version 並使用 main 分支的依賴配置,屬正常現象,bdslibrary 等依賴可能需要自行處理。注意模板註釋裡的 levilamina develop 已不可用(LeviLamina 倉庫現無 develop 分支)。正式發佈前若編譯/鏈接時缺少符號,可反饋給維護者。
BDS/LeviLamina 升級後,原本能用的 C++ 原生 mod 報內存訪問錯誤,怎麼辦?
C++ 原生 mod 與 BDS、LeviLamina 版本強綁定,換版本而未適配就可能出現內存訪問錯誤或崩潰。需要用對應版本的 LeviLamina SDK 重新編譯後才能使用;可以等作者發佈適配版,或自己拿源碼針對新版本重新編譯。
LeviLamina 客戶端(LLC)的 mod 能跨遊戲版本兼容嗎?相比自己寫 hook 的優勢在哪?
Mojang 每個版本都會改動代碼,除非 mod 用到的類都沒被改,否則一般需要針對新版本適配/重新編譯(寫得好的 mod 遷移成本低)。LL 的優勢是提供了大量符號對應的地址和完整的類成員頭文件(src/mc 下的 MC 頭文件)、各種封裝工具(Hook、事件、配置等),省去自己逆向補齊這些東西。
LeviLamina 的 C++(DLL)原生插件能跨 BDS 版本使用嗎?為什麼每次 BDS 更新原生插件基本都要更新?
LeviLamina 原生 mod 直接調用/Hook BDS 內部函數,BDS 版本變化後函數地址、簽名、結構體佈局經常改變,所以通常需要針對新版本重新編譯。只有當所調用的 BDS 函數在新版本中沒有變化時,DLL 才可能跨版本繼續用;不依賴任何 MC 內容的插件可較長期通用;依賴提供穩定接口的前置庫(如 GMLib)時跨版本性更好。小功能建議用腳本(LegacyScriptEngine 的 JS 等)編寫,跨版本更方便,作者停更也基本能繼續用。
PC 基岩版客戶端模組的 UI 在部分用戶電腦上不顯示,是什麼原因?
PC 基岩版並非都使用 DX12,部分設備會以 DX11 運行。如果模組的 UI 覆蓋層(如 ImGui)只針對 DX12 實現,DX11 用戶就會出現模組沒有 UI 的情況,需要同時兼容 DX11 和 DX12。
適用版本:PC 基岩版客戶端模組。未能從源碼或文檔中直接證實,僅供參考。
為新版 LeviLamina 編譯的原生 mod 能在舊版 LeviLamina 上運行嗎?
原生插件適配一般不考慮舊版本。只要 mod 沒有用到新版 LL 才開放的 MCAPI 或新版 MC 才有的 API,就有可能兼容舊版;否則需要針對舊版本重新編譯。建議直接把服務端/客戶端更新到最新版 LeviLamina。
LeviLamina mod 用 getLogger().debug(...) 輸出的調試日誌不顯示,怎麼調整日誌等級?有哪些等級?
Logger 的默認等級來自 PreLoader 配置:把 PreLoaderConfig.json 中的 logLevel 調高即可,LeviLamina 的 Logger 默認等級 = logLevel - 1(限制在 0~5),所以 logLevel 設為 5 對應 Debug,設為 6 對應 Trace。也可以在代碼裡對單個 Logger 調用 setLevel,例如 getSelf().getLogger().setLevel(ll::io::LogLevel::Debug)。等級枚舉(ll/api/io/LogLevel.h):
enum class LogLevel : int { Off = -1, Fatal, Error, Warn, Info, Debug, Trace };適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)
原生 C++ mod 作者如何像 LeviLamina 一樣接入 Sentry,讓自己 mod 的崩潰上報到自己的賬號?
自己註冊 Sentry 賬號並創建項目,把 DSN 寫進 mod 的 manifest.json 的 extraInfo:
"extraInfo": {
"sentryDsn": "https://<key>@<host>/<projectId>",
"sentryUploadType": "all"
}崩潰時 LeviLamina 的 CrashLogger 會把被懷疑的 mod 的信息上報到其 sentryDsn;sentryUploadType 為 "all" 時即使不是嫌疑 mod 也會上報。為了得到可讀堆棧,可在 GitHub Actions 發佈流程中用 sentry-cli 上傳調試符號(參考 LeviLamina 的 .github/workflows/release.yml 中 upload-to-sentry 任務:sentry-cli debug-files upload --include-sources)。另外記得給 mod 設置版本號(git tag),方便判斷用戶版本。JS 插件一般不需要配置。
適用版本:LeviLamina 1.0.0 及以上
使用 LeviLamina 的 ll::config::loadConfig 的 mod 更新後新增了配置項,舊配置文件卻加載失敗或部分配置被重置,是什麼機制?
ll::config::loadConfig 依據配置結構體中的 version 字段判斷是否需要更新:文件中缺少 version 或與代碼中的 version 不一致時,會調用 updater(默認 defaultConfigUpdater:以當前默認值為底,把文件中已有內容 merge_patch 進去)補全後再反序列化,並返回 false,提示調用方用 saveConfig 寫回文件(模板/LL 自身都是 loadConfig 返回 false 就 saveConfig)。如果開發者加了新字段卻沒改 version,就會被當作無需更新直接反序列化,缺字段或類型不符時反序列化拋異常;調用方捕獲後通常會用默認值重寫配置,於是出現部分配置丟失/被重置。
用戶側:把配置文件裡的 version 改成別的數字以觸發自動合併更新(保留原有配置),或刪除配置文件重新生成。
開發者側:新增或修改配置項時務必遞增 version。
適用版本:LeviLamina 1.x 及以上(當前版本仍適用)
通過 uuid 獲取 PlayerInfoEntry 後 name 字段全是空的,PlayerInfo 是否需要開啟 alwaysLaunch 才會記錄玩家名和 uuid?
是的。PlayerInfo 服務只有在被首次使用時才初始化,需要在 LeviLamina 配置中開啟 targeted.playerInfo.alwaysLaunch(默認 false),服務器啟動時就初始化 PlayerInfo,才會持續記錄玩家名與 uuid/xuid 的對應關係。
適用版本:LeviLamina 服務端當前版本
使用 LeviLamina 的配置讀寫接口(基於結構體反射)時,多層嵌套 JSON 怎麼定義?JSON 的 key 含有冒號(如 minecraft:stone)怎麼辦?
LL 內置了 ll::config::loadConfig / saveConfig(頭文件 ll/api/Config.h),按結構體反射自動映射,結構體需有整數成員 version(版本不一致時會調用 updater 並重寫文件)。配置路徑不要寫死,用 mod 自身的配置目錄(如 getSelf().getConfigDir())。嵌套對象直接在結構體裡嵌套 struct;key 不固定或含冒號時用 std::unordered_map<std::string, T> / std::map 表示,例如:
struct Item {
std::string dropitem;
int count;
};
struct Config {
int version = 1;
bool instant_destruction = false;
std::unordered_map<std::string, std::unordered_map<std::string, Item>> destroy;
};反射也支持 enum。默認值寫在成員初始化裡(需為聚合類型,不用構造函數)。
適用版本:LeviLamina 0.13 及以上至當前版本
給 LeviLamina mod 接入 Sentry 崩潰上報後,為什麼任何裝了我 mod 的服務器崩潰(即使和我的 mod 無關)都會給我發大量報告?該怎麼設置?
在 mod 的 manifest.json 的 extraInfo 中配置 sentryDsn 後,LL 的崩潰日誌器會上報崩潰。上報範圍由 extraInfo 的 sentryUploadType 控制:設為 "all" 時,只要裝了你 mod 的服務器發生任何崩潰都會上報;不寫或寫成 "all" 以外的任意值,則只在你的 mod 被判定為可疑模塊(崩潰棧涉及該 mod)時上報。另外服務端可通過 LL 配置 modules.crashLogger.uploadToSentry 關閉上報。
C++ mod 中要遍歷大範圍方塊(比如清除錯誤/未知方塊),怎樣做性能更好?
不要逐個調用 BlockSource 的 getBlock/setBlock。先拿到區塊,用 LevelChunk::getBlock(ChunkBlockPos) / LevelChunk::setBlock 按區塊處理,能省掉每次查區塊的步驟。數據層級是 BlockSource -> LevelChunk -> SubChunk -> Block,直接拿到全部 SubChunk(LevelChunk::mSubChunks)讀實際存儲最快;如果拿到的是序列化數據,就要從 block palette 取 index 再查 block indices。多線程直接 setBlock 會崩,修改要放回服務器主線程做。
適用版本:LeviLamina 服務端,當前版本
LeviLamina 1.21.70 版本中,mod 裡高頻調用 BDS 函數(如 LevelChunk 的 getBlock/setBlock)性能下降十倍以上,原因是什麼,如何提升?
有用戶分析:mod 中直接調用的 MC API(MCAPI)函數地址由 PreLoader 解析,而 PreLoader 為防護對函數做了包裝,導致高頻調用變慢。可選方案:改用 BlockSource 的虛函數 getBlock/setBlock(經虛表調用,實測比走被包裝的 LevelChunk 函數快);或用特徵碼(signature scan)直接拿到函數的真實地址。注意走 BlockSource 時,各種獲取失敗默認返回空氣方塊。
適用版本:當時為 LeviLamina 1.2.0 / BDS 1.21.70;新版本是否仍如此未知。未能從源碼或文檔中直接證實,僅供參考。
LeviLamina mod 開發中,監聽事件和直接 Hook 相比哪個開銷更小?為什麼大量 Hook 的插件熱卸載時可能卡死或崩潰?
優先用事件。Hook 本身有開銷:即使 hook 函數里什麼都不做也要多幾次跳轉;而且遊戲運行中安裝/卸載 hook 時,為了安全會暫停其它線程(GlobalThreadPauser,防止 CPU 正好執行到被修改的內存),hook 完再恢復,因此頻繁 hook/unhook 有代價,暫停時也可能發生死鎖導致卡死。事件的訂閱/取消只是在 EventBus 的哈希表容器裡插入/擦除。卸載崩潰的常見原因是註冊了回調(監聽器、定時任務等)卻沒有在卸載時取消,等回調被調用時 dll 已被卸載。
適用版本:LeviLamina 1.x 及以上
開發領地插件時,如何高效地根據方塊座標判斷其屬於哪個領地(避免每次遍歷所有領地比較 xyz 範圍)?
把領地數據全部讀到內存,並建立空間索引。例如建立映射表 維度 -> 區塊 -> 領地 ID 列表,即 Map<dimid, Map<chunk, Vector<Id>>>,一個區塊可對應多個領地;對於跨越多個區塊的大領地,計算出它覆蓋的所有區塊並逐一插入對應區塊的列表;查詢時先由座標算出區塊,再只比對該區塊下的領地,用 ID 去緩存取領地數據。也可使用 AABB 樹(如 https://github.com/lohedges/aabbcc)來加速包含檢測。
適用版本:通用設計思路,與版本無關。未能從源碼或文檔中直接證實,僅供參考。
有沒有分析 LeviLamina 模組內存(排查內存洩漏)的工具?
可以用 Visual Studio 的診斷工具,附加到 bedrock_server_mod.exe 進程後拍攝內存快照(Memory Snapshot)並對比,以定位內存洩漏。
適用版本:LeviLamina 服務端(Windows)。未能從源碼或文檔中直接證實,僅供參考。
LeviLamina C++ mod 開發有文檔/入門教程嗎?新手怎麼開始寫第一個 mod,怎麼找需要的 API 和頭文件?
有。入門教程“你的第一個 LeviLamina 模組”:https://levimc.org/zh-Hant/tutorials/develop/first-levilamina-mod/(舊地址 levilamina.liteldev.com/.../create_your_first_plugin、lamina.levimc.org/zh/developer_guides/tutorials/create_your_first_mod/ 等均已遷移)。LeviLamina 文檔站在 https://levimc.org/zh-Hant/LeviLamina/,其中有命令、事件、Hook、表單、物品、i18n、協程等 how-to 指南(developer_guides/how_to_guides)和 API 參考(api_reference,含配置 config 等);由頭文件生成的 Doxygen C++ 參考在 https://levimc.org/LeviLamina/api/。
Minecraft 原版類沒有文檔,主要靠閱讀頭文件(mc/...)和參考 LeviLamina 倉庫的測試代碼(src-test/,如 src-test/server/testCommand.cpp、EventTest.cpp)及其他開源 mod(如 LeviOptimize、LegacyMoney)。事件通過 ll::event::EventBus 監聽,可取消事件在回調裡調用 event.cancel()。腳本插件(LSE)的 API 文檔是另一套,見 LSE 文檔站。
新手可以用“萬能頭文件”一次性 include 全部頭文件,但會顯著拖慢編譯、讓 clangd 卡頓,大項目甚至內存不足,不推薦。
適用版本:當前所有版本(LeviLamina 1.x 及以上,文檔地址以 levimc.org 為準)
mod 開發中需要 LeviLamina 導出新的 MC API/符號/類成員/hook,應該在哪裡申請?能不能申請 RVA?
統一到 LiteLDev 的 mcapi-requests 倉庫(https://github.com/LiteLDev/mcapi-requests/issues)開 issue 申請,LeviLamina 主倉庫不再受理此類 issue。選擇 server 還是 client 都可以,維護者會統一歸類處理;需說明清楚 mod 用途。
沒必要申請 RVA:對已知符號名可以直接通過 LL 的符號解析獲取地址,例如 "符号名"_sym.resolve()(需 using namespace ll::literals;,另有 "符号名"_symp 直接得到緩存的地址);若解析失敗(返回 nullptr)則說明該符號當前不可用,仍需提交申請。
適用版本:LeviLamina 1.5 及以上(當前 26.60.x)
LeviLamina 的 API 只能在官網文檔一個個點開看嗎?有沒有方便搜索的方法?
官網 C++ Reference(由頭文件經 Doxygen 生成)可按 Ctrl+K 或 / 按名稱搜索類、函數、文件。更高效的做法是直接克隆 LeviLamina 倉庫,在本地用 VS Code 等編輯器全局搜索頭文件(src/ll/api 是 LL 自身 API,src/mc 為 BDS 公共頭文件,src-server / src-client 分別是服務端/客戶端專有頭文件)。
LeviLamina 的 API 文檔缺少客戶端相關內容(例如 ClientInstance),找頭文件很費勁怎麼辦?
客戶端相關頭文件在 LeviLamina 倉庫的 src-client 目錄下,例如 ClientInstance 位於 src-client/mc/client/game/ClientInstance.h。建議直接 clone 倉庫在 src-client 中搜索。另外當前官網 C++ Reference 的 Doxygen 輸入已包含 src-client/ll/api 和 src-client/mc,也可以在文檔中直接搜索客戶端類。
適用版本:LeviLamina 當前版本(含客戶端支持的版本)
mod 發佈版本號能否用 v[mod版本号]-mc[MC版本号](如 v0.3.1-mc26.51)這種格式來標註適配的 MC 版本?
不建議。按 SemVer 2.0.0,帶“-”的版本號會被理解為預發佈(測試)版本,lip 等工具也按 SemVer 解析(預發佈版本在版本選擇/自更新中會被區別對待)。如需附帶 MC 版本信息,可使用 build metadata(“+”後綴,例如 1.0.0+mc26.51)。
適用版本:當前所有版本(lip 使用 lip.toml,版本需為 SemVer 2.0.0)
發現 LeviLamina 頭文件裡某個數據包(packet)的結構定義有問題,應該怎麼反饋?
直接在 LeviLamina 的 GitHub 倉庫(LiteLDev/LeviLamina)提 issue,最好附上應該怎麼修(正確的結構/偏移等);也可以直接提 PR 修復(手寫內容需放在自動生成區塊之外)。
在 IDA 中看到 BDS 函數訪問 a1+416 這樣的成員偏移,如何知道它對應 LeviLamina 頭文件中哪個成員(如 mUnk 開頭的成員)?
打開 LeviLamina 倉庫 src/mc(或 src-server/src-client 下 mc/)中對應類的頭文件,查看 // member variables 區塊。當前頭文件的成員以 ::ll::TypedStorage<对齐, 大小, 类型> mXxx; 或 ::ll::UntypedStorage<对齐, 大小> mUnkxxxxxx; 形式聲明,頭文件裡沒有偏移註釋,需要從基類大小開始按每個成員的大小和對齊依次累加算出偏移,再和 IDA 裡的偏移(如 416 = 0x1A0)比對,就能找到對應成員。也可以在自己的代碼裡用 offsetof 或 static_assert 驗證。
適用版本:LeviLamina 當前版本(v26.x,成員使用 TypedStorage/UntypedStorage 佈局)
申請導出 MCAPI/符號(mcapi request)時,新模板有什麼要求?模板類可以申請嗎?一個 issue 能申請多少個?
現在的請求在單獨的倉庫 LiteLDev/mcapi-requests 用 Request 模板開 issue(標題如 Request symbols for <your-mod-name>),字段有:
- Mod:mod 的公開 GitHub 倉庫地址,要用當前 URL,
README.md裡要出現 issue 標題中的 mod 名。 - Platform:Server for Windows / Client for Windows / Client for Android。
- Justification:mod 做什麼、為什麼需要,最多 200 token,寫簡短即可,不要用 AI 寫長篇說明。
- Classes:需要成員變量的類,一行一個。
- Symbols:鏈接報錯裡未解析的符號,一行一個。
成員(Classes)和函數(Symbols)放在同一個模板裡;每個 issue 裡 Classes 和 Symbols 合計最多 64 行,issue 數量本身不限,需要就開。帶 < > 的模板類無法自動生成,需要單獨開請求由人工處理。
適用版本:當前(2026-11)的 LiteLDev/mcapi-requests 流程
開發 LeviLamina C++ mod 時有什麼好用的 WebSocket 庫?
LeviLamina 本身不提供 WebSocket API,需要用第三方庫。常見選擇有 websocketpp(https://github.com/zaphoyd/websocketpp,基於 C++11/asio)、uWebSockets(https://github.com/uNetworking/uWebSockets),也可以基於 TCP 庫自己實現。這些庫一般可以通過 xmake 的 add_requires 引入。
適用版本:當前所有版本(第三方庫,與 LL 版本無關)。未能從源碼或文檔中直接證實,僅供參考。
開發 LeviLamina mod 需要發包/抓包時,基岩版網絡協議文檔在哪裡可以查到?
Mojang 官方協議文檔倉庫:https://github.com/Mojang/bedrock-protocol-docs(仍在更新)。原 wiki.vg 的基岩版協議頁已經併入 Minecraft Wiki(minecraft.wiki 上的 Bedrock Edition protocol 相關頁面)。LeviLamina 在 src/mc/network/packet/ 下提供了各數據包的頭文件(如 CameraPacket.h、CameraInstructionPacket.h),可以直接構造使用。
適用版本:LeviLamina 當前版本
給 LeviLamina 頭文件(src/mc)提 PR(如為類補充默認構造函數或手寫函數)時有什麼規範要注意?
src/mc 的頭文件大多是工具生成的,生成器會和現有內容合併,手寫內容只要符合約定就不會在重新生成時丟失。規範:
- 不要把手寫代碼夾在生成區域裡(
// auto generated inclusion list、// auto generated forward declare list、// NOLINTBEGIN~// NOLINTEND之間、MCAPI/MCFOLD/MCTAPI/MCNAPI聲明、::ll::TypedStorage<...>成員佈局),也不要往生成列表裡添加或調整順序,否則會影響後續合併。 - 手寫的聲明單獨放在一個
public:區塊(放在// member variables之上),用LLNDAPI/LLAPI導出。 - 實現寫在同目錄的
.cpp裡,不要內聯在頭文件中。 - 默認構造函數可以把
// prevent constructor by default區塊裡的聲明改成= default或= delete,這樣重新生成時會保留。
適用版本:LeviLamina 當前版本
能不能寫一個 LeviLamina mod 檢測 BDS 假死(卡死),然後自動結束進程並重啟?
不建議只靠 BDS 裡的 mod:LL mod 和 BDS 共用主線程,主線程卡住時依賴 tick 的 mod 邏輯也會一起停。可靠的做法是外部看門狗:在遊戲 tick 裡定時發心跳(如通過 pipe),由外部進程(或單獨的守護線程)在長時間收不到心跳時判定為卡死。用外部程序重啟服務器、生成 dmp 也更方便。一些服務器面板自帶這個功能。
適用版本:當前所有版本(通用設計建議)。未能從源碼或文檔中直接證實,僅供參考。
逆向基岩版、還原被編譯器內聯掉的函數時,有沒有公開可用的帶符號的二進制可以參考?
可以用 macOS 版 Minecraft 教育版(Minecraft Education)。它的二進制裡帶有大量符號(x86_64 和 arm64 雙架構,合計 110 多萬符號),和基岩版是同一套代碼庫,逆向參考價值高。下載入口:https://aka.ms/meeclientmacos 或 https://education.minecraft.net/zh-hans/get-started/download(2026-09 時正式版為 1.26.32,beta 為 1.26.30,版本會繼續更新)。可以配合 bindiff 等工具和 Windows 版做函數匹配,用 x86_64 部分可以避免跨架構匹配效果差的問題。
適用版本:截至 2026-09 的 Minecraft Education macOS 版本;後續版本是否仍帶符號需自行確認。未能從源碼或文檔中直接證實,僅供參考。