構建 LeviLamina 模組:工具鏈
想用 C++ 開發 LeviLamina 原生 mod,開發環境怎麼搭?LL/BDS 頭文件和庫從哪裡來?能否自己建 VS 工程手動配置?寫好後怎麼放到服務器上運行?
不建議自己建 VS 工程手動配置頭文件和庫。推薦流程:安裝 Git、Visual Studio(勾選“使用 C++ 的桌面開發”,提供 Windows SDK 和 C++ 庫)、LLVM(安裝時加入 PATH;當前模板用 set_toolchains("clang-cl") 以 clang-cl 編譯)和 xmake;用 GitHub 上的 LiteLDev/levilamina-mod-template “Use this template”新建倉庫,在 xmake.lua 中修改 target 名,並用 add_requires("levilamina 26.60.*", ...) 固定與服務器前兩段版本號一致的 LeviLamina 版本;在項目目錄執行 xmake f -y -p windows -a x64 -m release 和 xmake,頭文件和庫由 xmake 自動拉取並構建。拉依賴失敗多半是網絡問題,可為 xmake 配置 GitHub 鏡像代理或 HTTP 代理;找不到指定 LeviLamina 版本時執行 xmake repo -u。編輯器任選,推薦 VS Code + C/C++、XMake、clangd 擴展;也可用 xmake project -k vsxmake 生成 VS 工程。頭文件寫法如 #include "ll/api/command/CommandRegistrar.h"、#include "mc/world/actor/player/Player.h",不要套用 LSE 的 API 命名。構建產物在 bin\<mod名>\ 下(包含 dll 和 manifest.json),把整個文件夾複製到服務器的 mods 目錄,重啟服務器後由 LeviLamina 加載。詳見 https://levimc.org/zh-Hant/tutorials/develop/first-levilamina-mod/
適用版本:LeviLamina 1.x 及以上
LeviLamina 服務端 mod 能直接給客戶端(LeviLamina client)用嗎?能否一個 DLL 雙端通用?移植到客戶端要做哪些適配?
不能通用,必須分別編譯服務端版和客戶端版兩個 DLL:依賴 LeviLamina 的 mod 加載時會解析所有用到的 MC API 符號,缺失就加載失敗;而客戶端與 BDS 的符號差異很大(大量內聯、客戶端多了 client 相關內容),且 Actor 等類在兩端的成員和虛表也不同。適配步驟:
- 參考最新 levilamina-mod-template 更新
xmake.lua、manifest.json和 GitHub Actions workflows;編譯客戶端版用xmake f --target_type=client再構建(默認 server),兩端特有代碼可分別放src-server/src-client。 - 包描述文件現為
lip.toml(format 4),在默認 variant 下分別聲明side = "server"和side = "client"兩個條目(舊的tooth.jsonclient label 已被取代),依賴統一寫github.com/LiteLDev/LeviLamina。 - 命令註冊用
CommandRegistrar::getServerInstance()(即getInstance(false))或getClientInstance()。 - 用到服務端特有的東西需改動(如
PropertiesSettings:src-server下有完整成員與函數,src-client下只是空殼結構體);hook 等代碼需要實際測試。
另外客戶端每進一次世界相當於開一次服務端,mod 必須正確實現 disable/卸載邏輯。
適用版本:LeviLamina 1.8 及以上(lip.toml 部分 26.60.8 及以上)
C++ mod 項目如何指定/更新/回退所依賴的 LeviLamina 版本?改了版本後構建仍報錯怎麼辦?
在 mod 項目的 xmake.lua 裡給 levilamina 包名後加版本號,例如 add_requires("levilamina 26.60.8", {configs = {target_type = get_config("target_type")}})(不寫版本則選用包倉庫 versions.txt 裡的最新版本;也可寫完整 40 位 commit hash 或分支名如 levilamina main 使用開發中版本,此時需自行處理 bdslibrary 等依賴。注意模板註釋裡寫的 levilamina develop 已不可用——LeviLamina 倉庫現在沒有 develop 分支,開發分支是 main)。改完版本後依次執行:xmake repo -u(更新 levimc-repo 等包倉庫,讓本地知道新版本)、xmake c -a(清理全部構建緩存),必要時 xmake f -c 重新配置,再執行 xmake 構建;如用 VSCode/clangd 補全,再執行 xmake project -k compile_commands 重新生成。注意:寫了包倉庫中未收錄的版本號時,xmake 會把它當作 git 分支去拉取,從而報 Remote branch ... not found 之類的錯誤。
xmake 構建 mod 時指定 levilamina 某版本報 Remote branch x.y.z not found in upstream origin,或警告 Unknown version: x_y_z, will use main branch dependencies,怎麼辦?
原因是本地的 xmake 包倉庫(LiteLDev/xmake-repo,項目中名為 levimc-repo)的 versions.txt 裡沒有這個版本:xmake 在版本列表裡匹配不到時,會把寫的版本號當成 git 分支名去拉取 LeviLamina 倉庫,於是報 Remote branch x.y.z not found;而 Unknown version: x_y_z, will use main branch dependencies 是 levilamina 包腳本在找不到 versions/<x_y_z>.lua 時打印的警告(用 commit 或分支指定版本時也會出現,屬正常,會回退使用 main 分支的依賴配置)。可能是本地倉庫沒更新,也可能是 LeviLamina 發版後 xmake-repo 尚未(或沒有)收錄該版本(例如目前 xmake-repo 就沒有收錄 v26.20.2、v1.6.2)。處理辦法:
- 執行
xmake repo -u更新包倉庫,必要時xmake c -a(或刪除項目下的.xmake目錄)後重試。 - 若 xmake-repo 中仍沒有該版本,在
add_requires裡改用 LeviLamina 對應 tag 的完整 40 位 commit hash(短 hash 會被當作分支名而同樣失敗),或換用已收錄的相鄰版本。
版本號寫不寫 v 前綴都能匹配。下載失敗時還需檢查網絡/代理。
用 xmake 構建 LeviLamina mod 時下載依賴包(levilamina、entt、expected-lite、libhat 等)或拉取包倉庫一直失敗/很慢,怎麼辦?
絕大多數是訪問 GitHub 的網絡問題。xmake 和 git 不一定走系統代理,可按以下方式處理:
- 給 xmake 設代理:
xmake g --proxy=http://127.0.0.1:端口;或在同一終端設環境變量後再構建(cmd:set HTTP_PROXY=http://127.0.0.1:端口與set HTTPS_PROXY=http://127.0.0.1:端口);同時給 git 設代理:git config --global http.proxy http://127.0.0.1:端口。也可把代理軟件開成 TUN(系統級透明代理)模式。Steam++ 之類不要用 hosts 加速模式。 - 使用鏡像:自行編寫一個 pac 文件(如
%LOCALAPPDATA%\.xmake\pac.lua或任意絕對路徑),在其中定義function mirror(url) ... end把 github.com 地址改寫為可用的鏡像地址,然後xmake g --proxy_pac=<该文件>。注意:舊教程(包括 LeviLamina 構建文檔)中的xmake g --proxy_pac=github_mirror.lua依賴 xmake 內置的scripts/pac/github_mirror.lua,該文件已在 xmake v2.9.8(2025-01)起被移除,新版 xmake 直接這樣寫無效。詳見 xmake 文檔“網絡優化”:https://xmake.io/zh/guide/package-management/network-optimization.html - 如果項目或全局配置裡設置了不適合你網絡的代理/鏡像(例如海外或開著代理卻用了國內鏡像),把它刪掉或改回 GitHub 源。
- 應急辦法:從別人處拿到已下載好的包,放入 xmake 包緩存目錄
%LOCALAPPDATA%\.xmake\packages\<首字母>\<包名>(如 levilamina 在packages\l\levilamina);或手動下載源碼包後用xmake g --pkg_searchdirs=<绝对路径>指定本地搜索目錄。 - 若某個 git 倉庫緩存拉取卡住,可進入 xmake 報錯的那個倉庫緩存目錄手動
git fetch後重試;也可先xmake repo -u、xmake c -a清理後重新構建。
用 xmake 構建 LeviLamina mod(levilamina-mod-template)時拉取倉庫/下載依賴報 SSL 證書錯誤,例如 fatal: unable to access 'https://github.com/LiteLDev/xmake-repo.git/': SSL certificate problem: unable to get local issuer certificate(或 xmake-mirror/build-artifacts.git),怎麼辦?
這是本機訪問 GitHub 時的網絡/證書問題(本地缺少或不信任 GitHub 的證書鏈,常見於代理/加速器劫持 HTTPS),不是 xmake 或 LeviLamina 的問題。LeviLamina 的包倉庫 levimc-repo(https://github.com/LiteLDev/xmake-repo.git)和大部分依賴都託管在 GitHub 上。處理方法:
- 檢查網絡/代理環境,使用穩定可靠的代理正常訪問 GitHub(Watt Toolkit 這類加速器會替換證書,效果不穩定)。
- 如果確實是本機證書鏈缺失,可在瀏覽器訪問 GitHub 導出站點證書,安裝到“受信任的根證書頒發機構”。
- 對 xmake 通過 curl 下載包時的證書校驗失敗,可執行全局配置
xmake g --insecure-ssl=y跳過 SSL 校驗(見 xmake FAQ“下載包提示證書校驗失敗怎麼辦”)。
構建本身:在項目目錄先 xmake repo -u,再 xmake f -y -p windows -a x64 -m release(或 -m debug),最後 xmake,產物在 bin/;用 Visual Studio 的話需按 xmake 文檔生成 vsxmake 工程後再構建。需事先安裝 git;當前模板使用 clang-cl 工具鏈,還需安裝 LLVM(模板 CI 使用 LLVM 22)。
執行 xmake f -m debug 等命令時提示 note: the following packages were not found in any repository (check if they are spelled correctly): -> levilamina -> levibuildscript,或找不到指定版本的 levilamina,怎麼解決?
- 確認
xmake.lua中添加了 LiteLDev 的包倉庫:add_repositories("levimc-repo https://github.com/LiteLDev/xmake-repo.git")(舊模板遺留的過時配置可以刪掉,以最新 levilamina-mod-template 的xmake.lua為準)。 - 執行
xmake repo -u更新包倉庫。 - 仍找不到時,清理緩存:刪除項目目錄下的
.xmake文件夾(或xmake c -a),再執行xmake repo -u,然後重新xmake f -m debug(或 release)並構建。 - 如果
xmake.lua中寫死了add_requires("levilamina x.x.x")的版本,確認該版本存在於 xmake-repo 中,可改為最新版本、去掉版本號使用最新,或使用add_requires("levilamina develop")(使用 develop 時需自行添加 bdslibrary)。
編譯 levilamina-mod-template 時 xmake 安裝 levilamina 依賴包(installing levilamina)卡幾個小時,或報錯 error: unable to parse semver,怎麼解決?
levilamina 包在安裝時會從源碼在本地編譯,並需從 GitHub 拉取 xmake-repo 和各依賴,本身就比較慢;長時間卡住或報 unable to parse semver 通常是網絡問題:xmake-repo 沒能拉取下來,導致找不到指定版本。解決:
- 使用代理的 TUN(虛擬網卡)模式,或在 PowerShell 中為 xmake 設置代理環境變量(如
$env:all_proxy="http://127.0.0.1:端口"),或用xmake g --proxy="http://127.0.0.1:端口"為 xmake 全局設置代理。 - 刪除當前項目目錄下的
.xmake後重試。 - 按標準流程:克隆模板後執行
xmake repo -u、xmake f -m debug(或xmake f -y -p windows -a x64 -m release)、xmake。 - 版本號處也可以寫 commit hash 或 branch;必要時可手動下載卡住的包。
注意當前模板使用 clang-cl 工具鏈,需要先安裝 LLVM(CI 使用 LLVM 22)。
用 VSCode 開發 LeviLamina C++ mod(levilamina-mod-template)時,xmake 能編譯通過,但編輯器裡頭文件找不到、滿屏紅線、LL/BDS 的類和函數沒有補全,怎麼解決?
頭文件不需要手動下載或拷到 src 下,也不要手動往 includePath 裡填路徑:LeviLamina 及其依賴由 xmake 包管理下載。編輯器缺的是編譯數據庫 compile_commands.json。
- 用 VSCode 打開包含
xmake.lua的項目根目錄,先執行一次xmake f -y -p windows -a x64 -m release和xmake,讓依賴下載完成。 - 生成編譯數據庫:在項目根目錄執行
xmake project -k compile_commands(生成到根目錄);或安裝 VSCode 的 XMake 擴展,Ctrl+Shift+P 執行“XMake: Update Intellisense”。注意 XMake 擴展默認把compile_commands.json生成到.vscode目錄,而 clangd 默認只在項目根目錄(及其父目錄)找,所以要麼改 XMake 擴展的輸出目錄,要麼給 clangd 加參數--compile-commands-dir=.vscode,要麼直接用命令行生成到根目錄。 - 推薦用 clangd(需安裝 LLVM,模板自帶
.clangd配置);生成後重啟 clangd / Reload Window 並等待索引完成。clangd 與微軟 C/C++(cpptools)的 IntelliSense 衝突,用 clangd 時應關閉 cpptools 的 IntelliSense。若堅持用 cpptools,則把C_Cpp.default.compileCommands指向生成的compile_commands.json。 - 頭文件或依賴版本更新後需重新生成
compile_commands.json;配置混亂時可刪掉.vscode下的生成配置重來。只要 xmake 能編譯通過,編輯器的誤報不影響構建。
其他 IDE:Visual Studio 用 xmake project -k vsxmake 生成 sln;CLion 可直接導入根目錄的 compile_commands.json,標準庫標紅時把工具鏈改為 Visual Studio。構建本身需要 Visual Studio(“使用 C++ 的桌面開發”工作負載,提供 Windows SDK)+ LLVM(模板用 clang-cl 編譯),MinGW 不能用。
用 Visual Studio 開發 LeviLamina C++ mod,直接“打開文件夾”後沒有補全、#include 報錯或“轉到定義”找不到頭文件,生成的工程裡也看不到頭文件,怎麼辦?
不要用 VS 的“打開文件夾”方式打開 xmake 項目。頭文件由 xmake 包管理下載,所以先在項目目錄執行一次 xmake f -y -p windows -a x64 -m release 和 xmake 下載依賴並編譯,再用 xmake 生成 VS 工程:
xmake project -k vsxmake -m "debug,release"然後打開生成的 vsxmake 目錄裡的 .sln,即可正常索引和補全。
注意:
- vsxmake 只把
add_headerfiles聲明的頭文件放進工程,不會掃描add_includedirs。當前模板的xmake.lua已有add_headerfiles("src/**.h");如果你用.hpp或其他目錄,需要自己補上,例如add_headerfiles("src/**.h", "src/**.hpp")。 - 在 vsxmake 生成的 sln 裡新建文件時,文件可能被放到生成目錄而不是
src下,需要手動移到src並重新生成工程。 - 也可以用 xmake 生成 CMake 工程(
xmake project -k cmakelists)後用 VS 的 CMake 支持打開,或使用 VS 的 xmake 擴展;VSCode 則按 compile_commands 方式配置。
開發 LeviLamina C++ mod 時怎麼斷點調試?為什麼用 VS/VSCode 直接“啟動”bedrock_server_mod.exe 調試不行?
用“先啟動服務器、再附加調試器”的方式,不要用調試器直接啟動 BDS(自 LeviLamina 1.2.0 起,PreLoader 的運行時保護會讓在加載 Runtime Data 前就掛著調試器的啟動失敗,報“Failed to load Runtime Data ... please attach it after Runtime Data is loaded”)。
- Visual Studio:正常運行
bedrock_server_mod.exe,然後“調試 → 附加到進程”,選擇bedrock_server_mod.exe。 - VSCode:在
.vscode/launch.json中使用"type": "cppvsdbg", "request": "attach"的配置後選擇進程附加。當前 levilamina-mod-template 已自帶.vscode/launch.json,提供“BDS attach”/“GDK attach”配置:安裝 VSCode 擴展 Tasks Shell Input,設置環境變量MC_BDS_DEBUG_PATH(BDS 可執行文件完整路徑,客戶端用MC_GDK_DEBUG_PATH),可選MC_SYMBOLS_PATH(符號目錄),即可一鍵啟動並自動附加。 - 需要調試啟動早期(如
load()/enable())時:先在命令行set PL_DEBUG=1,再運行bedrock_server_mod.exe,PreLoader 會在 Runtime Data 加載後暫停等待調試器附加,附加後繼續運行。 - 能否看到源碼取決於 mod dll 對應的 pdb:模板
xmake.lua中set_symbols("debug")會生成 pdb,有 pdb 才能看源碼、下斷點,否則只能看反彙編。更底層可用 x64dbg/WinDbg。 - LSE 的 JS 等腳本插件不能用這種方式調試。
- LeviLamina 在初始化 CrashLogger 時若檢測到已有調試器(例如用
PL_DEBUG=1在早期就附加),會提示“Debugger detected, CrashLogger will not be enabled”並不啟用 CrashLogger;服務器啟動後再附加時 CrashLogger 已啟用,但調試器仍會先捕獲異常。
適用版本:LeviLamina 1.2.0 及以上
BDS 已從 MSVC 換成 clang 編譯,LeviLamina 的 C++ mod 也必須跟著換編譯器嗎?還能用 MSVC 編譯嗎?
必須換。新版 BDS 改用 clang 編譯,LeviLamina 被迫跟隨改用 clang-cl。MSVC 和 clang 很多特性不同,同一份代碼在兩種編譯器下 ABI 可能完全不同,繼續用 MSVC 編譯 mod 會出現事件監聽異常、功能失效,甚至開服直接崩潰。請使用最新 levilamina-mod-template 的配置:xmake.lua 中 set_toolchains("clang-cl")(並保留模板裡針對 clang_cl 的 cxflags),本地需安裝 LLVM(模板 CI 使用 LLVM 22)。
適用版本:LeviLamina 26.20.0 及以上
LeviLamina 及其 C++ mod 能用 CMake 構建嗎(像 Endstone 插件那樣)?
官方只支持 xmake(levilamina-mod-template)。如果確實要用 CMake,可以用 xmake 生成 CMake 工程:xmake project -k cmakelists,但生成的依賴庫路徑都指向 xrepo 目錄;此外 mod 鏈接前需要 levibuildscript 的 linkrule 做 prelink(用 prelink.exe 和 bedrock_runtime_data 處理目標文件,並添加 /DELAYLOAD:bedrock_runtime.dll),在 CMake 中必須自己補上這一步才能正常鏈接。想徹底脫離 xmake 就需要自己編寫 CMakeLists.txt 並補全所有依賴。
沒有 Windows 環境(macOS、WSL/Linux、GitHub Codespaces)能編譯 LeviLamina C++ mod 嗎?
官方只支持在 Windows 上編譯 mod:模板使用 clang-cl 工具鏈(需要 Windows SDK 與 MSVC STL 頭文件/庫),macOS/Linux 下沒有官方支持,BDS 也不能在 mac 上運行。沒有 Windows 環境時,推薦把源碼推到 GitHub 倉庫,用 GitHub Actions 的 windows-latest runner 構建(mod 模板自帶 .github/workflows/build.yml),在 Actions 運行頁的 Artifacts 下載產物(需登錄 GitHub 才能下載)。若堅持在 Linux 下折騰,可嘗試 msvc-wine(https://github.com/mstorsjo/msvc-wine)提供 Windows SDK/MSVC 環境,但無官方保證。
用 levilamina-mod-template 構建時 manifest.json 中版本號總是 0.0.0,或提示 Failed to parse version tag, using 0.0.0,版本號在哪裡設置?
版本號不是取自 tooth.json,而是構建時由 levibuildscript 的 modpacker 通過 git describe --tags --abbrev=0 讀取 git tag,並按 vX.Y.Z 格式解析;沒有 tag 或格式不對就使用 0.0.0。因此:
- 要用
git clone獲取倉庫(直接下載 zip 不含.git); - 打一個帶
v前綴的標籤,如git tag v0.1.0,再構建。
也可以在 xmake.lua 中手動指定:add_rules("@levibuildscript/modpacker", {modVersion = "1.0.0"})。
適用版本:使用 levibuildscript modpacker 的 mod 模板(當前版本)
mod 模板裡的 MemoryOperators.cpp 有什麼用?可以刪掉嗎?刪掉後 mod 加載報錯怎麼辦?
該文件內容為 #define LL_MEMORY_OPERATORS + #include "ll/api/memory/MemoryOperators.h",讓 mod 使用 LeviLamina 統一的全局 operator new/delete(BDS 自定義了內存分配,LL 使用 mimalloc,所有 mod 必須統一)。當前版本 LeviLamina 會檢查 mod 是否導出 ll_memory_operator_overrided,否則直接拒絕加載並報 <mod> will not be loaded because it isn't using the unified memory allocation operator。所以不要刪除它;刪了就恢復該文件。如果想換個位置,也可以在 mod 的某一個(且只能一個)源文件中寫上述兩行來代替。若編譯時出現 MemoryOperators 相關報錯,先執行 xmake repo -u 更新 xmake-repo 後重新構建。
適用版本:LeviLamina 1.0 及以上
mod 本地能編譯,但在 GitHub Actions(或新克隆的倉庫)上編譯失敗(頭文件相關錯誤),怎麼辦?
LeviLamina 已改用 clang-cl,Actions 的 windows runner 自帶的 LLVM 版本可能太舊,需要在 workflow 裡安裝新版 LLVM(與最新模板一致):
- name: Setup LLVM
uses: ZhongRuoyu/setup-llvm@v0
with:
llvm-version: 22並在構建前執行 xmake repo -u 更新 xmake-repo。最好直接對照最新 levilamina-mod-template 的 .github/workflows/build.yml 同步。如果是 LeviLamina 新版本依賴尚未就緒導致的失敗,可在 xmake.lua 中固定版本,如 add_requires("levilamina x.x.x")。
適用版本:LeviLamina 26.20.0 及以上
C++ mod 依賴的第三方 DLL(如放在 mod 目錄下的庫,或 jvm.dll 等不在 PATH 中的外部 DLL)找不到,mod 加載失敗(連 onLoad 都沒執行),怎麼辦?
mod DLL 被加載時系統會解析其導入表並加載依賴 DLL,找不到就加載失敗(錯誤碼 126/127,LeviLamina 會附帶依賴診斷信息)。Windows 沒有 rpath:LeviLamina 在加載 native mod 前會把該 mod 的目錄追加到 PATH,所以放在 mod 目錄(或 BDS 根目錄)下的依賴 DLL 能被找到。對於位置不固定的外部 DLL(如 jvm.dll),要麼把其目錄加入系統 PATH,要麼不要靜態鏈接導入,改為運行時用 LoadLibrary/GetProcAddress(或 LeviLamina 的 ll::sys_utils::DynamicLibrary 封裝)動態加載,這樣可以按“配置文件 → 環境變量 → 註冊表”的順序查找 JAVA_HOME;也可使用鏈接器的 /DELAYLOAD 選項延遲加載(levibuildscript 的 linkrule 本身就用它延遲加載 bedrock_runtime.dll)。
LeviLamina C++ mod(xmake 模板)如何引入第三方庫(如 soci)?soci 運行時報 backend 找不到怎麼辦?
如果庫在 xmake 官方倉庫(xmake-repo)中,直接在 xmake.lua 裡 add_requires 並在 target 中 add_packages 即可,soci 就有,可通過包配置開啟後端,如 add_requires("soci", {configs = {mysql = true}})(其他後端同理)。官方倉庫沒有的,可用 xmake 引入 vcpkg 包,如 add_requires("vcpkg::soci")(參考 xmake 文檔“添加 vcpkg 的依賴包”),否則只能自行編譯出 dll/靜態庫再鏈接。soci 運行時會用 LoadLibrary 動態加載各 backend DLL,所以 backend DLL 需放在能被搜索到的位置(當前工作目錄、PATH,或 mod 目錄——LeviLamina 會把 mod 目錄加入 PATH),或通過 backend 搜索路徑指定,否則報 backend 找不到。另外 xmake-repo 的 soci 默認構建為靜態庫(shared=false),此時 backend 是靜態鏈接進來的,不會去找 DLL,需要在使用前顯式註冊,如調用 soci::register_factory_mysql(),或直接以 soci::mysql 工廠對象創建 session。注意當前 mod 用 clang-cl 編譯,第三方 C++ 庫最好也由 xmake 用同一工具鏈構建。
LeviLamina(LL3)的 mod 模板能用來寫 LiteLoaderBDS(LL2)的插件嗎?LL2 的 C++ 插件模板在哪?
不能。levilamina-mod-template 只適用於 LeviLamina。LL2 的 C++ 插件模板是 https://github.com/LiteLDev/liteloaderbds-plugin-template,該倉庫與 LiteLoaderBDS 本體均已歸檔,不再維護,建議遷移到 LeviLamina。
適用版本:當前版本(LiteLoaderBDS 已歸檔)
用 levilamina-mod-template 創建 C++ mod 項目後沒有 include(頭文件)文件夾,LeviLamina 的頭文件在哪裡?
不是缺文件,模板本身就沒有單獨的 include 目錄(舊教程截圖較老)。直接使用 https://github.com/LiteLDev/levilamina-mod-template,先執行一次 xmake(構建)或 xmake f 配置,xmake 會通過 levimc-repo 自動拉取 LeviLamina 等依賴。頭文件位於 xmake 的包緩存目錄中,Windows 下為 C:/Users/<用户名>/AppData/Local/.xmake/packages/l/levilamina/<版本>/<哈希>/include。
BDS 不再提供 PDB 之後,LeviLamina 的 mod 怎麼鏈接符號、還能不能 hook?
由 bedrock runtime data(“magic blob”,xmake 包 bedrockdata)取代 PDB。blob 不含明文符號,而是“符號 hash -> RVA”的映射。構建 mod 時在鏈接前調用 prelink 工具,把用到的外部符號 hash 後去 blob 中查找並生成用於鏈接的 fake lib;運行時也以同樣方式解析。bedrockdata 和對應版本的 prelink 由 xmake 依賴自動下載,無需手動處理。hook 寫法不變,可參考 LeviLamina 倉庫 src-test/client/jsonUITest.cpp。PeEditor 目前只負責向 bedrock_server.exe 注入 PreLoader 生成 bedrock_server_mod.exe,不再涉及 PDB。
適用版本:BDS 1.21.20+ / LeviLamina 0.13+ 至當前
C++ mod 訂閱 ServerCommandRegisterEvent 後,事件監聽器沒有任何輸出,怎麼回事?
多半是編譯器不對。新版 BDS/LeviLamina 使用 clang-cl 編譯,mod 也必須用 clang-cl 編譯(更新到最新的 levilamina-mod-template,其 xmake.lua 中已有 set_toolchains("clang-cl"),並安裝 LLVM)。用 MSVC 編譯的 mod 雖然能編譯、能加載,但類型名稱與 BDS/LL 不一致,事件監聽會失效。
適用版本:LeviLamina 26.x(BDS 改用 clang-cl 編譯之後)
C++ mod 中引用 RemoteCall 頭文件時 clangd 全紅、compile_commands.json 裡沒有對應包的信息,怎麼辦?寫給其他 C++ mod 用的前置應該用 RemoteCall 嗎?
先確認 xmake.lua 中 add_requires 並在 target 中 add_packages 了對應包(RemoteCall 現在的 xmake 包名為 legacyremotecall);然後在 VS Code 中 Ctrl+Shift+P 執行 xmake 插件的 UpdateIntellisense(或 xmake project -k compile_commands)重新生成 compile_commands.json,再 restart clangd。另外,給其他 C++ mod 用的前置不建議用 RemoteCall,直接用 __declspec(dllexport) 導出函數即可(參見官方文檔接口導出指南)。
GitHub Actions 上構建 mod 失敗,日誌裡有與 cmake 相關的警告,如何排查?
看日誌中更靠上的 error 而不是 warning。曾有案例是 runner 環境缺少 Python(某些依賴包用 cmake 構建時需要),在 workflow 中加入 actions/setup-python 後解決。建議以最新 levilamina-mod-template 的 workflow 為基礎(需包含 setup-xmake、setup-llvm、xmake repo -u 等步驟)。
適用版本:使用 GitHub Actions 構建 mod 時。未能從源碼或文檔中直接證實,僅供參考。
LeviLamina mod 如何適配新的遊戲版本(如 26.20)並做版本控制?構建時會自動下載對應 SDK 嗎?
目標 LeviLamina/遊戲版本在 xmake.lua 中通過 add_requires("levilamina x.x.x", ...) 指定(不寫版本則用最新),構建時 xmake 會拉取對應版本的 LeviLamina 包。發佈用的包元數據現在寫在 lip.toml 中(舊版模板為 tooth.json),需在其 deps 中填寫對應的 LeviLamina 版本範圍,如服務端變體 "github.com/LiteLDev/LeviLamina" = "26.60.*"(模板 lip.toml 中客戶端變體用 ">26.60.6 <26.61.0",因為 26.60.6 是最後一個 tooth.json 版本)。另外 xmake.lua 中不必再 add_requires nlohmann_json,LeviLamina 包已將其作為公開依賴傳遞。
適用版本:當前 levilamina-mod-template(lip.toml 格式)
LeviLamina mod 開發文檔裡生成 VS Code 配置的 xmake 命令應該在哪裡執行?
在任意終端執行都可以,只要當前目錄是項目根目錄(含 xmake.lua)。這是 xmake 自帶的功能(如 xmake project -k compile_commands 生成 compile_commands.json),詳細說明見 xmake 文檔;VS Code 的 xmake 插件也能自動生成/更新這些配置。
未能從源碼或文檔中直接證實,僅供參考。
LeviLamina mod 使用事件(如 ServerStartedEvent)時鏈接報找不到符號,怎麼解決?
可能是 xmake 緩存了舊版 LeviLamina 包導致頭文件與庫不匹配。執行 xmake repo -u,刪除 %LocalAppData%\.xmake 以及項目目錄下的 .xmake、build 文件夾,再重新 xmake f 和 xmake 構建。同時確認使用 clang-cl 工具鏈編譯。
未能從源碼或文檔中直接證實,僅供參考。
LeviLamina mod 用 xmake 編譯一直失敗,怎麼排查?
- 確保工具鏈最新:Visual Studio/MSVC 生成工具(提供 Windows SDK 與 STL)及 LLVM(mod 用
clang-cl編譯); - 執行
xmake repo -u; - 刪除
%LocalAppData%\.xmake,再刪除項目目錄中的.xmake、build等緩存; - 重新執行
xmake f -y -p windows -a x64 -m release並留意 configure 階段的報錯,然後xmake構建。
LeviLamina 每次 MC 版本更新附帶的 MC 頭文件(src/mc 下的 header)是人工編寫的還是自動生成的?
現在是工具自動生成的(只有很早期的版本是人工寫的),因此 MC 頭文件基本沒有註釋,頭文件中能看到 // auto generated inclusion list、// auto generated forward declare list 之類的標記。
LeviLamina 能否像 Java 的 library 前置 mod 那樣,讓一個 mod 作為依賴庫給其他 mod 調用?會不會產生多份數據副本?
可以。在前置 mod 中用 __declspec(dllexport) 導出函數/類(參考 LeviLamina 的 LLAPI 宏,例如下面的寫法,並在前置 mod 的 xmake.lua 中 add_defines("MOD_EXPORT")):
#ifdef MOD_EXPORT
#define MODAPI __declspec(dllexport)
#else
#define MODAPI __declspec(dllimport)
#endif使用方 dllimport 並鏈接其導入庫,同時在使用方 mod 的 manifest.json 中填寫依賴,例如 "dependencies": [{ "name": "RequiredMod", "version": "^1.2.3" }](也有 optionalDependencies、loadBefore)。LeviLamina 會按依賴關係排序,先加載依賴,使用方無需自己加載前置 dll。Windows 對 dll 有引用計數,同一個 dll 只加載一次,其全局變量也只有一份,不會產生多個副本。
適用版本:LeviLamina 當前版本(Windows native mod)
VSCode clangd 中某些被宏包裹的代碼區域(#if/#ifdef 塊)變灰沒有補全,怎麼讓它顯示補全?
需要讓該宏在編譯參數中生效:在 xmake.lua 中用 add_defines 添加該宏,然後在 VSCode 中 Ctrl+Shift+P 執行 XMake: UpdateIntellisense 重新生成 compile_commands.json,再執行 clangd: Restart language server。直接在 .clangd 里加 -D 參數效果不穩定。未啟用的宏分支 clangd 不會提供補全。
適用版本:使用 xmake + VSCode clangd 開發 mod 的環境。未能從源碼或文檔中直接證實,僅供參考。
Windows 用戶名為中文時,xmake 編譯 LL mod / 安裝依賴包出現亂碼路徑失敗,怎麼辦?
非 ASCII 路徑會導致 xmake 全局緩存/包目錄路徑出錯。可以改用英文用戶名的新賬戶,或把 xmake 全局目錄改到純英文路徑:設置環境變量 XMAKE_GLOBALDIR 指向一個英文目錄後重新構建。
適用版本:Windows 下使用 xmake 構建 mod,且用戶目錄含非 ASCII 字符。未能從源碼或文檔中直接證實,僅供參考。
xmake 包描述(如給 xmake-repo 提交包或寫自定義包)裡 add_versions 的哈希值是什麼,怎麼得到?
如果包用的是源碼壓縮包下載地址(set_urls/add_urls 指向 zip/tar.gz),哈希值是該版本壓縮包的 SHA-256,用於校驗下載內容;如果包用的是 git 倉庫地址(如 https://github.com/xxx/yyy.git),則填對應版本的 git commit hash。
適用版本:當前 xmake / LiteLDev xmake-repo
xmake 構建 LeviLamina mod 每次要編譯十幾到二十分鐘,且會把 LeviLamina 重新編譯,是什麼原因?
levilamina xmake 包是從源碼編譯安裝的。通常是前置依賴(如 gmlib、bsci 等)要求的 LeviLamina 版本(或 target_type 等配置)與 mod 本身 add_requires 的不一致,導致 xmake 需要編譯兩份不同版本的 LeviLamina。讓所有依賴統一使用同一個 LeviLamina 版本/配置即可避免重複編譯。
適用版本:使用 xmake 構建依賴 levilamina 包的 mod
xmake 構建 mod 出現 prelink/bedrockdata 相關的緩存異常,刪除項目文件也不好,如何清理?
刪除 xmake 全局目錄(Windows 默認 C:\Users\<用户名>\AppData\Local\.xmake,即 %LOCALAPPDATA%\.xmake,不是項目目錄)的 packages 下的 prelink、bedrockdata、levilamina 包,然後重新 xmake f 配置並構建;也可執行 xmake c -a,或刪除 mod 項目目錄下的 .xmake 和 build 目錄。實在不行重裝 xmake。
適用版本:LeviLamina 當前版本(Windows,xmake 構建)
xmake 編譯 LeviLamina mod 時報錯找不到頭文件 #include "pl/Config.h"(或 LL SDK 頭文件內容異常),清緩存也沒用,怎麼解決?
這通常是網絡問題導致 xmake 下載的 LeviLamina/preloader 等依賴包不完整(例如以前下載中斷過,之後直接使用了殘缺的包)。pl/Config.h 來自 preloader 包。解決:刪除 C:\Users\<用户名>\AppData\Local\.xmake 下的包緩存(或整個目錄)後重新下載;或從能正常編譯的電腦複製 xmake 的 packages 文件夾。網絡不好時可給 xmake 配置 GitHub 鏡像,例如新建 github_mirror.lua:
function mirror(url)
url = url:gsub("github.com", "<镜像域名>")
return url
end
function main(url, host)
return true
end然後執行 xmake g --proxy_pac=<该文件绝对路径>(該文件之後不能刪除)。
適用版本:使用 xmake 構建 mod、網絡訪問 GitHub 不穩定的環境。未能從源碼或文檔中直接證實,僅供參考。
為什麼在 xmake 項目裡添加 LeviLamina 依賴(add_requires("levilamina"))時會連帶拉取 PreLoader?
這是正常的。xmake 的 levilamina 包在安裝時會從源碼構建 LeviLamina,而 LeviLamina 自身的 xmake.lua 裡 add_requires("preloader ...")(LeviLamina 由 PreLoader 負責加載,運行時也依賴 PreLoader),所以安裝 levilamina 包時會一併拉取 preloader 包。
用新版 LeviLamina(如 26.51.x 及以後)編譯 mod 時報錯 ll/api/reflection/Reflection.h: error: no member named 'to_underlying' in namespace 'std',怎麼辦?
需要開啟 MSVC STL 的 C++23 庫特性:在 mod 的 xmake.lua 的 target 中加入 _HAS_CXX23 宏,按最新 levilamina-mod-template 的寫法:
add_defines("NOMINMAX", "UNICODE", "_HAS_CXX23=1")模板仍是 set_languages("c++20") + set_toolchains("clang-cl"),靠 _HAS_CXX23=1 打開 std::to_underlying 等 C++23 庫函數。
適用版本:LeviLamina 26.51 及以上,使用 levilamina-mod-template 結構的 mod
使用 levilamina-mod-template 時,模板裡的 MyMod(類名)和 my_mod(命名空間)應該怎麼改?
命名空間 my_mod 改成自己 mod 的名字;類名 MyMod 可以隨意改(例如改為 Entry 或你的 mod 名)。注意要同步修改:src/mod/MyMod.h 與 MyMod.cpp 中的類名和命名空間、MyMod.cpp 末尾的 LL_REGISTER_MOD(my_mod::MyMod, my_mod::MyMod::getInstance());,否則會編譯報錯。另外 xmake.lua 中 target("my-mod") 也要改成你的 mod 名(manifest.json 中的 name 由構建腳本按 target 名自動填充)。
適用版本:當前 levilamina-mod-template
用 xmake 構建 levilamina-mod-template(native mod)時報錯,或提示無法獲取 cxx 程序(找不到 C++ 編譯器),怎麼辦?
通常是編譯環境沒裝全。當前模板在 Windows 上使用 clang-cl 工具鏈,需要:
- 安裝 Visual Studio 2022 及以上,勾選“使用 C++ 的桌面開發”工作負載(含 MSVC 與最新 Windows SDK,
clang-cl依賴其標準庫與 SDK); - 安裝 LLVM(官方 CI 當前使用 LLVM 22),並確保
clang-cl在PATH中; - 安裝/更新 xmake 到 3.0.0 以上。
裝好後用 xmake c -a 清理緩存,再 xmake f -c -y -p windows -a x64 -m release 重新配置並構建。
適用版本:當前 levilamina-mod-template / LeviLamina 26.x
使用最新 LeviLamina 版本時,mod 項目的 CI 構建一直失敗,應該用什麼工具鏈?
新版 LeviLamina 需要用 clang-cl(LLVM)編譯。按最新 levilamina-mod-template 更新 CI:在 workflow 中加入
- name: Setup LLVM
uses: ZhongRuoyu/setup-llvm@v0
with:
llvm-version: 22然後依次執行 xmake repo -u、xmake f -a x64 -m release -p windows -v --target_type=${{ matrix.target_type }} -y、xmake -v -y。xmake.lua 也要同步模板(set_toolchains("clang-cl")、_HAS_CXX23=1 等)。
適用版本:LeviLamina 26.x(2026-08 起官方 CI 改用 LLVM)
依賴都填了最新版本,但編譯 mod 時 LeviLamina 頭文件報錯(提示平臺宏 LL_PLAT_S / LL_PLAT_C 相關問題),怎麼解決?
原因是沒有定義平臺宏。現在 levimc-repo 的 levilamina xmake 包會根據 target_type 自動給 mod 加上 LL_PLAT_S(server)或 LL_PLAT_C(client),模板裡不再需要手寫。解決方法:
xmake repo -u更新包倉庫到最新;- 按最新模板寫
add_requires("levilamina", {configs = {target_type = get_config("target_type")}})並聲明option("target_type"); - 若使用的舊版包倉庫不會自動添加,可在 target 中手動加入:
if is_config("target_type", "server") then
add_defines("LL_PLAT_S")
else
add_defines("LL_PLAT_C")
end適用版本:LeviLamina 26.x 及以上
寫 LeviLamina C++ mod 時,overloaded + std::visit 等寫法 IDE(clangd)報錯,如何讓 clangd 使用正確的 C++ 標準和 include 路徑?
報錯是 clangd 沒拿到項目的編譯參數(語言標準、include 路徑、宏)導致的。在項目目錄執行:
xmake project -k compile_commands生成 compile_commands.json,clangd 會自動讀取其中的編譯參數(模板為 set_languages("c++20") 並定義 _HAS_CXX23=1)。修改 xmake.lua 或依賴後需重新生成。
升級 LeviLamina 版本或更新 Visual Studio 後,用 xmake 編譯 mod 出現莫名其妙的編譯錯誤,該怎麼處理?
先執行 xmake c -a 清理全部構建緩存後重新編譯;不行的話刪除項目下的 .xmake 和 build 文件夾,再 xmake f -c -y 重新配置並編譯。同時用 xmake repo -u 更新包倉庫,並確認 xmake.lua / CI 與最新 levilamina-mod-template 一致(clang-cl 工具鏈、LLVM 22、_HAS_CXX23=1)。此前出現過 VS2026/2022 都編譯不了的情況,屬於微軟編譯器側問題,後來已修復,更新 VS 即可。
升級 LeviLamina(如 1.9.2 及以後)後自己的 mod 本地和 GitHub Actions 構建都出錯,怎麼解決?
更新 mod 的 xmake.lua,參照 levilamina-mod-template 最新模板:加入 target_type 選項(option("target_type") 默認 server,可選 server/client),並用 add_requires("levilamina", {configs = {target_type = get_config("target_type")}}) 引入依賴;target 末尾按 is_config("target_type", "server") 區分服務端/客戶端源碼。GitHub Actions 同步模板的 build.yml(matrix 構建 server 和 client,xmake f ... --target_type=${{ matrix.target_type }})。
適用版本:LeviLamina 1.9.x 及以後(含 26.x)
升級到新版 LeviLamina(26.20 起)後編譯 mod 時 clang 崩潰,怎麼辦?
把 mod 的 xmake.lua 和 GitHub Actions workflow 同步為 levilamina-mod-template 最新版本(模板使用 set_toolchains("clang-cl") 及配套 cxflags,CI 用 ZhongRuoyu/setup-llvm 安裝 LLVM 22),本地也使用對應版本的 LLVM,清理 xmake 緩存(xmake f -c)後重新構建。
適用版本:LeviLamina 26.20 及以後
同一份 mod 代碼,依賴 LeviLamina 26.40.1 能編譯通過,換到 26.40.4/26.40.5 後報 LL 頭文件裡的編譯錯誤(代碼本身沒引用這些頭文件),怎麼辦?
從 LeviLamina 26.20 開始必須使用 clang-cl 編譯,不能再用 MSVC(cl.exe)。xmake.lua 參照 levilamina-mod-template 設置 set_toolchains("clang-cl");GitHub Actions 參考模板安裝 LLVM 22。切換工具鏈/版本後清理 xmake 緩存:刪除 .xmake 目錄,或執行 xmake clean -a 和 xmake f -c 後重新配置。
適用版本:LeviLamina 26.20 及以後
在 LeviLamina mod 的 xmake 工程中使用 vcpkg 提供的庫時出現鏈接錯誤(缺少依賴庫的符號),怎麼解決?
xmake 引入 vcpkg 包時可能未正確處理其傳遞依賴,需要手動補齊。推薦直接改用 xmake 自身的包(add_requires 安裝所需庫及其依賴,如 zlib、libuv,再 add_packages);也可以在 target 裡手動 add_links 缺失的依賴庫。
適用版本:使用 xmake 構建的 LeviLamina mod。未能從源碼或文檔中直接證實,僅供參考。
如何編譯並啟用 LeviLamina 自帶的測試(如 EventTest)?
構建 LeviLamina 時啟用 tests 選項:xmake f --tests=y(可加 --target_type=server/client),然後 xmake。會引入 gtest 並編譯 src-test 目錄(服務端事件測試在 src-test/server/EventTest.cpp)。xmake 配置是粘性的,切換配置後行為異常可刪除項目下 .xmake 目錄或 xmake f -c 重新配置。
適用版本:LeviLamina 26.x 當前版本
如何自己編譯 LeviLamina 本體?
準備 XMake 3.0.0+、LLVM/Clang(clang-cl 需在 PATH 中)、Visual Studio 2022 或其生成工具(C++ 桌面開發工作負載,提供 clang-cl 依賴的 Windows SDK 與標準庫)和 Git。在倉庫根目錄執行 xmake 即構建服務端(默認);用 xmake f --target_type=client 後再 xmake 構建客戶端,可加 --tests=y 啟用測試。服務端也可用 -p linux(clang 工具鏈)面向 Linux x86_64 構建,客戶端只能在 Windows 構建。緩存異常時執行 xmake c -a 和 xmake f -c。
適用版本:LeviLamina 26.20 及以後
開發 LeviLamina C++ mod 用什麼 IDE 合適?用 VSCode 可以嗎?
可以,常用 VS Code + xmake(配合 xmake 擴展、clangd 擴展)開發,官方 mod 模板自帶 .clangd 和 .vscode/launch.json 調試配置。Visual Studio 體積大,直接用它寫 LL mod 不太方便(如需可用 xmake project -k vsxmake 生成工程)。無論用什麼編輯器都必須安裝工具鏈:當前模板與 LeviLamina 在 Windows 上使用 clang-cl 工具鏈(set_toolchains("clang-cl")),需要安裝 LLVM(clang-cl 在 PATH 中),同時安裝 Visual Studio 2022("使用 C++ 的桌面開發")或 VS 2022 生成工具以提供 MSVC 標準庫和 Windows SDK。
適用版本:當前版本(LeviLamina 26.x,官方 levilamina-mod-template)
開發 LeviLamina C++ mod 時編譯報錯(成員函數聲明與定義不匹配、非靜態成員函數調用錯誤),如何解決?
兩個常見原因:
- 頭文件聲明與
.cpp定義的const修飾不一致——要麼頭文件和源文件都加const,要麼都不加; - 非靜態成員函數不能直接用類名調用,需先獲取實例,例如模板中的
MyMod::getInstance().getSelf()(在類自身的成員函數內部可直接調用getSelf(),無需getInstance())。
這是通用的 C++ 規則,示例基於官方 mod 模板。
開發 LeviLamina mod 時用 /Wall 編譯會出現大量警告,應該開 /Wall 嗎?
不建議開 /Wall。/Wall 會對結構體對齊填充等情況報警告(例如 struct 中 void* 後跟 bool,提示 7 字節填充未使用),噪音極大(當前使用的 clang-cl 下 /Wall 等同 -Weverything,噪音更大)。LeviLamina 自身使用 /W4(外加 /w44265、/w44289、/w44296、/w45263、/w44738 等個別升級),官方 mod 模板也默認 /W4,mod 用 /W4 即可。
開發 LeviLamina mod 時,有沒有方便查看 ll 命名空間層級和可用函數/頭文件的方法?
使用官方 levilamina-mod-template:它通過 xmake 的 add_packages("levilamina") 引入 LeviLamina 全部頭文件,在 VS Code 中配合 clangd(模板自帶 .clangd,xmake 擴展或 xmake project -k compile_commands 生成 compile_commands.json)後,輸入 ll:: 即可通過補全看到所有命名空間和函數,懸停可看到所在頭文件。也可以直接瀏覽 LeviLamina 倉庫 src/ll/api 目錄或官方 API 文檔(docs.levimc.org)。
適用版本:當前版本(LeviLamina,官方 mod 模板)
開發 LeviLamina mod 用的 xmake 能像 Visual Studio 一樣一鍵構建嗎?推薦用什麼編輯器?
推薦使用 VS Code,安裝 xmake 擴展和 clangd 擴展來開發和構建(xmake 擴展提供一鍵構建/調試)。命令行下在項目根目錄執行 xmake f -y -p windows -a x64 -m release 後運行 xmake 即可構建,產物在 bin/ 下。
適用版本:當前版本(LeviLamina,官方 mod 模板)
開發 LeviLamina 客戶端 mod 時遊戲一啟動就閃退,來不及掛調試器,怎麼調試?
可以在 mod 的 DllMain(或 mod 加載入口)裡先延遲約 10 秒,或循環等待調試器附加(如 while (!IsDebuggerPresent()) Sleep(100);),這樣就有時間把調試器掛到遊戲進程上;也可以直接用調試器啟動 Minecraft 進程。官方 mod 模板的 .vscode/launch.json 也提供了 "GDK attach"/"BDS attach" 配置(需安裝 Tasks Shell Input 擴展並設置 MC_GDK_DEBUG_PATH / MC_BDS_DEBUG_PATH),可自動啟動進程並附加調試器,但它在進程穩定約 3 秒後才附加,過早崩潰仍需配合上述等待方法。
適用版本:當前版本(Windows)
想做安卓原生 mod,在 Termux/arm64 Linux 上克隆 LeviLamina 後執行 xmake f -p linux -a arm64 報錯 `arm64` is not a valid complation arch for this project, please use one of x86_64,怎麼辦?
LeviLamina 只支持 x86_64:客戶端僅 windows|x64,服務端為 windows|x64 和 linux|x86_64,不能用於編譯安卓 mod。安卓端原生 mod 走另一套體系:由 Android 版 LeviLauncher 通過 Preloader SDK(LiteLDev/preloader-android,pl:: API)加載,應參考教程“寫你的第一個 Android 原生模組”(https://levimc.org/zh-Hant/tutorials/develop/first-android-mod/)及 LeviLamina 文檔中 developer_guides/android 下的 API 頁面,而不是 LeviLamina。
想用 Visual Studio 手動配置 vcxproj 開發 LeviLamina 插件,LL 導出的 lib 去哪找?
官方推薦使用 levilamina-mod-template(xmake)開發。LeviLamina 不再單獨提供可直接鏈接的 SDK lib:xmake 的 levilamina 包會從源碼用 clang-cl 編譯 LeviLamina 及其全部依賴,手動寫 vcxproj 需要自己編譯一份 LeviLamina 並配置所有依賴庫,非常麻煩。如果想用 Visual Studio,可以在模板項目中執行 xmake project -k vsxmake 生成 VS 工程,由 xmake 負責依賴與鏈接。
適用版本:LeviLamina 26.x
打包 LeviLamina mod 時,包描述文件裡依賴的 LeviLamina 版本不改會怎樣?是否默認為最新版?
不會自動取最新版,需要手動把依賴改成目標版本。當前模板已用 lip.toml 取代 tooth.json:在 [variants."".deps] 中設置 "github.com/LiteLDev/LeviLamina" 的版本範圍(模板服務端為 "26.60.*",客戶端為 ">26.60.6 <26.61.0",客戶端依賴使用裸 id 而非 "#client"),同時在 xmake.lua 中把 add_requires("levilamina x.x.x") 改為目標版本,否則依賴的 LL 版本不對。
適用版本:lip.toml 格式(LeviLamina 26.60.6 之後的模板);舊 tooth.json 同理
構建客戶端 mod 時 xmake 報錯 error: Invalid option: --target_type=client,是什麼原因?
--target_type 是項目 xmake.lua 裡用 option("target_type") 聲明的配置項(取值 server/client,默認 server),只有 xmake.lua 中聲明瞭該選項才能傳這個參數。報這個錯說明你的 xmake.lua 是舊版或被改過、沒有 target_type 選項。請用最新 levilamina-mod-template 中的 xmake.lua(其中 option("target_type") 並以 add_requires("levilamina", {configs = {target_type = get_config("target_type")}}) 傳給 levilamina 包),並確認 xmake 為最新版本(xmake --version),然後執行 xmake f -a x64 -m release -p windows --target_type=client -y,再 xmake -v -y 構建。
適用版本:LeviLamina 26.x,當前 levilamina-mod-template
本地用 xmake 構建 LeviLamina 本體失敗(換了多個 LLVM 版本都不行),但 CI 正常,怎麼排查?
- 用
xmake -v查看實際調用的是哪個 LLVM/clang-cl:如果裝過 Visual Studio 的 LLVM(Clang)組件,xmake 可能優先用 VS 自帶的 LLVM 而不是你單獨安裝的版本,需要卸載或避開。 - 執行
xmake repo -u更新包倉庫後再xmake -v -y重新構建——依賴包(如parallel-hashmap)版本描述的問題會在倉庫側修復,本地倉庫不更新就會一直失敗。
可參照 CI 的做法(安裝 LLVM 22 後 xmake repo -u,再 xmake f / xmake)。
適用版本:LeviLamina 26.x
構建 mod 時安裝 levilamina 包失敗,日誌中 glm 等依賴報 error STL1000: Unexpected compiler version, expected Clang 20 or newer(VS2026 / 新版 MSVC STL),怎麼解決?
說明 xmake 檢測到並使用了系統裡另外安裝的低於 20 版本的 LLVM Clang,與新版 MSVC STL 不兼容。卸載舊版 Clang 後,要麼在 Visual Studio Installer 中勾選“適用於 Windows 的 C++ Clang 工具”(clang-cl)組件,要麼單獨安裝新版 LLVM(官方模板 CI 使用 LLVM 22);否則會報 toolchain("clang-cl"): not found。可用 xmake -v 確認實際使用的 clang 版本。詳細失敗日誌位於 %LOCALAPPDATA%\.xmake\cache\packages\...\levilamina\<版本>\installdir.failed\logs\install.txt。
適用版本:LeviLamina 26.x
某個開源的 LeviLamina 原生 mod 作者已停更,如何自行更新到新版 LeviLamina?
自己 fork 該倉庫,把 xmake.lua 換成 levilamina-mod-template 裡最新的版本(並修改 mod 名、LeviLamina 版本,必要時同步 lip.toml/manifest.json),根據新頭文件調整 include 路徑和 API(Mojang 可能刪除或改動了部分函數,需要改寫),編譯通過後給原倉庫提 PR。
用 LeviLamina 開發 mod 時,還需要像 LL2 那樣手動把 BDS 的 lib 文件放到項目目錄嗎?
不需要。依賴由 xmake 自動下載:levilamina 包及其依賴都在 LiteLDev 的 xmake-repo(模板中以 levimc-repo 添加)中,構建時自動拉取。當前版本 BDS/客戶端的鏈接數據由 bedrockdata 包(bedrock-runtime-data,按 target_type 區分 server/client)提供,舊的 bdslibrary 包僅用於 1.21.3 以前的老版本。使用 levilamina develop 等未登記版本時,包會按 main 分支依賴加載(模板註釋提示開發版可能需自行補充 BDS 庫依賴)。
適用版本:LeviLamina 0.x 及以上
用 levilamina-mod-template 創建的項目在 Visual Studio 裡輸入代碼時總被自動格式化成奇怪的樣子,怎麼關掉?
mod 模板根目錄自帶 .clang-format 配置文件,VS 會優先讀取它來格式化代碼。按自己的習慣修改或刪除項目根目錄下的 .clang-format 即可(或在 VS 中關閉鍵入時自動格式化)。
適用版本:當前 levilamina-mod-template
用 levilamina-mod-template 創建的項目,模板更新後如何同步到自己的項目?
沒有自動同步,只能手動對照模板修改(主要是 xmake.lua,以及 .github/workflows、lip.toml 等)。通過 "Use this template" 創建的倉庫與模板沒有 git 歷史關聯,即使想 merge 也需要自己處理衝突。
用 levilamina-mod-template(xmake)開發 mod 時 CLion 無法代碼補全,怎麼辦?
在項目根目錄執行 xmake project -k cmakelists 生成 CMakeLists.txt,然後用 CLion 打開生成的 CMake 工程。(也可執行 xmake project -k compile_commands 生成 compile_commands.json 供 clangd/CLion 使用,模板已自帶 .clangd 配置。)
用 levilamina-mod-template,把 add_requires 裡的 LeviLamina 指定為舊版本(如 1.4.4)後,執行 xmake project -k compile_commands -v -y 報“無法打開包括文件”,編譯失敗(用最新版就正常),怎麼辦?
通常是下載 preloader 包時網絡出問題,xmake 拉下來的包內容不完整/不對。刪除對應版本的 preloader 包目錄和 xmake 緩存後重新執行即可,例如:
- 刪除
%LOCALAPPDATA%\.xmake\packages\p\preloader\<版本号>(如v1.15.3); - 刪除
%LOCALAPPDATA%\.xmake\cache; - 重新執行
xmake project -k compile_commands -v -y(或xmake -y)。
適用版本:使用 xmake + levimc-repo 構建 LeviLamina mod 的所有版本
開發 LeviLamina C++ mod 時,控制台輸出中文/UTF-8 亂碼,怎麼設置 UTF-8 編碼輸出?
推薦使用 mod 自帶的 Logger(如 getSelf().getLogger())輸出,LeviLamina 在 Windows 控制台下通過 WriteConsoleW 輸出,中文不會亂碼。若必須用 printf/std::cout 直接輸出,可在啟動時引入 Windows.h 並執行:
SetConsoleCP(CP_UTF8);
SetConsoleOutputCP(CP_UTF8);
DWORD mode;
GetConsoleMode(GetStdHandle(STD_OUTPUT_HANDLE), &mode);
SetConsoleMode(GetStdHandle(STD_OUTPUT_HANDLE), mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING);同時確保源碼以 UTF-8 編譯(模板已帶 /utf-8)。也可開啟 Windows 的“Beta: 使用 Unicode UTF-8 提供全球語言支持”,但可能導致其他程序亂碼。
適用版本:Windows 下的 LeviLamina mod / 普通控制台程序
用 xmake 構建 LeviLamina mod 時報錯 error: package(bedrockdata): version(xxx) not found!(例如 1.21.60.10-server),該怎麼處理?
這是本地 xmake 包倉庫(levimc-repo)緩存過舊導致的。執行 xmake repo -u 更新倉庫後重新構建即可。規律:某個包版本實際已發佈,但 xmake 提示找不到,就說明需要更新倉庫緩存。
適用版本:使用 xmake + levimc-repo 構建的所有 LeviLamina 版本
用 xmake 編譯 LeviLamina mod(如 LegacyRemoteCall 相關項目)時內存耗盡(OOM)、編譯器堆空間不足甚至 VSCode 崩潰,怎麼辦?
原因是頭文件 include 過多(如 include_all、大量 magic_enum 宏展開)導致每個編譯進程佔用大量內存。解決辦法是降低並行編譯數量:xmake -j <num>(例如 xmake -j 2),同時關閉其他佔內存的軟件;也可以減少不必要的大頭文件包含。
適用版本:當前版本(取決於機器內存)
用最新的 levilamina-mod-template 創建的項目無法編譯,怎麼辦?
需要加上 _HAS_CXX23 的 define。模板已在 commit https://github.com/LiteLDev/levilamina-mod-template/commit/2d01125a7b8982d04019d1a006c0276d0006f5d6 中加上:
add_defines("NOMINMAX", "UNICODE", "_HAS_CXX23=1")更新模板或手動在 xmake.lua 的 target 中添加該 define 即可。
適用版本:2026-10 之後的 LeviLamina(26.x)與 levilamina-mod-template
用最新的 levilamina-mod-template 編譯面向舊版 LeviLamina(如 1.4.1)的 mod,GitHub Actions 構建 client 版本失敗(舊版沒有 client 版),如何讓 action 只構建服務端?
LeviLamina 從 1.9.0 才正式支持客戶端。面向舊版本時,在 .github/workflows/ 下的 build.yml 和 release.yml 中把 matrix.target_type 裡的 client 項刪除,只保留 server 構建即可。另外 lip.toml 中 side = "client" 的那個 variant 也應一併刪除,並把 LeviLamina 依賴版本改成你實際使用的版本。
適用版本:LeviLamina 1.9.0 之前版本,使用新版模板的項目
編譯 LeviLamina C++ 插件時報錯 C4819:該文件包含不能在當前代碼頁(936)中表示的字符,如何解決?
給編譯器加上 UTF-8 編譯參數 /utf-8(xmake.lua 中 add_cxflags("/utf-8"))。官方 mod 模板的 xmake.lua 默認已帶此參數;如果仍出現,也可能是代碼裡寫錯了符號(如中文標點)或頭文件用錯引起的,需檢查源碼,並確保源文件以 UTF-8 保存。
編譯 LeviLamina mod 時 xmake 報錯(與 preloader 包有關),怎麼修復?
刪除 xmake 緩存和對應版本的 preloader 包後重新編譯:
- 刪除
C:\Users\%USERNAME%\AppData\Local\.xmake\cache; - 刪除
C:\Users\%USERNAME%\AppData\Local\.xmake\packages\p\preloader\<版本号>(如v1.15.5); - 重新執行
xmake編譯。
適用版本:使用 xmake + levimc-repo 構建的所有 LeviLamina 版本
編譯 LeviLamina mod 時報 "clear": 不是 "CompoundTag" 的成员 等編譯錯誤,怎麼解決?
當前 CompoundTag 沒有 clear() 成員函數,但其內部的 TagMap 成員 mTags 是 public 的,可直接用 nbt.mTags.clear() 清空。另外 LeviLamina 要求 xmake 3.0.0 及以上(xmake.lua 中 set_xmakever("3.0.0")),xmake 版本過舊(如 2.9.x)時請先 xmake update 升級再構建;bedrockdata 等依賴由 levilamina 包按版本自動引入,無需手動 add_requires 舊版本號。
適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)
編譯 mod 時報 LeviLamina 頭文件缺少它所依賴的其他頭文件(某些類型未定義),怎麼解決?
LeviLamina 的 mc 頭文件是工具自動生成的,部分頭文件可能缺少所需的 include(只有前向聲明)。解決方法:在 mod 中用到該頭文件的源文件裡,手動 #include 缺失類型所在的頭文件即可;如果難以定位,也可以向 LeviLamina 提 PR 補全該頭文件的 include。
適用版本:LeviLamina 當前版本
自行編譯 LeviLamina(或用模板編譯 mod)編譯不通過,而舊版本能正常編譯,怎麼辦?
檢查 LLVM/clang 版本。LeviLamina 和 mod 模板在 Windows 上使用 clang-cl 工具鏈,Visual Studio 自帶的 clang/LLVM 往往太舊;請安裝/更新到較新的 LLVM(官方 CI 使用 LLVM 22),同時確保 xmake >= 3.0.0,再重新編譯。
適用版本:LeviLamina 26.x
調試 LeviLamina 插件崩潰時,CrashLogger 總是比 VS 調試器先搶到異常,怎麼方便地調試?
開發時可使用 debug 版的 LeviLamina(release 同時提供 server/client 的 debug 構建包),報錯會有更完整的堆棧。CrashLogger 在啟動時若檢測到調試器(IsDebuggerPresent)會自動不啟用,因此直接用調試器啟動 BDS 即可避免搶異常;若要在啟動後再附加調試器,可在 LeviLamina 配置文件(mods/LeviLamina/config/Config.json)中把 modules.crashLogger.enabled 設為 false 關閉 CrashLogger。
適用版本:LeviLamina 1.x 及以上