跳到正文
本頁目錄

LeviLamina 模組的報錯與崩潰

在 LeviLamina mod 中從子線程/線程池(ThreadPoolExecutor、std::thread、定時器線程)調用 MC API 或發包(如 forEachPlayer、sendPacket、TextPacket),導致崩服或客戶端提示“服務器發送了破損的數據包”,怎麼處理?

BDS 的遊戲邏輯和發包都不是線程安全的(內部無鎖,多線程同時寫發送隊列會崩潰),所有 MC/BDS API(包括 sendPacket,即使是 TextPacket)都必須在服務器主線程調用;這是 mod 自身的問題,LeviLamina 不會“修復”。

做法:耗時工作可以放線程池,但涉及 MC API 的部分要切回主線程,例如:

cpp
ll::thread::ServerThreadExecutor::getDefault().execute([]{ ... });

或用協程:

cpp
ll::coro::keepThis([]() -> ll::coro::CoroTask<> { co_await 20_tick; ... }).launch(ll::thread::ServerThreadExecutor::getDefault());

協程是否在主線程取決於 launch 時使用的 Executor:只有 ServerThreadExecutor 是主線程,ThreadPoolExecutor 不是。

定時/週期任務按 tick 來做(1 tick = 50ms),不要高頻(如 1ms)發包:客戶端不會以更高頻率處理,RakNet 在高頻發包下不穩定,容易被判為破損數據包;高精度音樂播放可改用資源包內置 ogg,或轉換為按 tick 播放的格式(如 nbs)。另外 addon 不能發包,出現破損數據包時應排查原生 mod。

LeviOptimize 曾提供的多線程發包優化(PacketSenderOpt)已移除,現在不能依賴它在非主線程發包;若確需在其他線程發送,只能先在主線程外用 Packet::write 序列化成二進制流再通過自帶加鎖的第三方接口(如 GMLIB 的二進制流發包)發送,屬於第三方方案。

適用版本:LeviLamina 1.0 及以上(當前 v26.60.8);主線程限制適用於所有版本

自己寫的 LeviLamina C++ mod 構建成功,但運行時讓 BDS 崩潰(時而內存訪問錯誤、時而除以 0),控制台看不到有用的報錯,怎麼定位到自己代碼裡的出錯位置?

用調試器而不是到處加 logger 猜:

  1. 先正常啟動 bedrock_server_mod.exe,再用 Visual Studio“調試 → 附加到進程”(或 VSCode cppvsdbg attach、WinDbg)附加;需要捕獲啟動早期的崩潰時,先 set PL_DEBUG=1 再啟動,讓 PreLoader 等待調試器附加。不要用調試器直接啟動 bedrock_server_mod.exe,新版 LeviLamina 下會失敗。
  2. 異常發生時調試器會斷在出錯位置;沒直接指到你的代碼時,順著調用堆棧往上找到自己 mod 的幀,查看變量。也可以在可疑代碼處打斷點單步調試。
  3. 要看到源碼需要 mod 對應的 pdb(模板默認 set_symbols("debug") 會生成)。
  4. 不掛調試器時,LeviLamina 內置的 CrashLogger 會在崩潰時輸出堆棧,如果是自己的 mod,堆棧裡的函數名一般能直接對應到代碼位置(若 CrashLogger 初始化時就已掛著調試器,如 PL_DEBUG=1 方式,CrashLogger 不啟用)。

適用版本:LeviLamina 1.2.0 及以上(含當前 26.x);思路適用於所有版本

關服時出現提示某插件(如依賴 GMLIB 的插件)無法 disable / failed to disable,會導致崩服嗎?

不會。關服時 LeviLamina 按加載順序的逆序逐個 disable mod;disable 某個 mod 時若仍有未禁用的 mod 依賴它,會返回錯誤“{0} still depends on {1}”;mod 的 disable() 返回 false 時返回“The mod cannot be disabled”。這些錯誤在 disableAllMods 中只以 Warn 級別打印日誌,不影響正常關服。若真的崩服,是別的原因(如某 mod 關閉時的代碼),應安裝 CrashLogger 定位。

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

LeviLamina C++ mod 在方塊破壞等事件中延遲執行邏輯時,拿到的方塊座標隨機亂跳、按座標取到的方塊是空氣,是什麼原因?

延遲執行的回調/協程裡引用了事件對象中的數據(例如捕獲了 ev.pos() 的引用或 ev 本身),事件回調返回後這些對象已被銷燬,回調執行時讀到的是懸垂數據。延遲執行時必須把需要的值(BlockPos、維度 id 等)按值拷貝/捕獲後再傳入,例如 [pos = BlockPos(ev.pos()), dim = ...] 或在協程中先拷貝到局部變量,而不是捕獲引用。當前版本的延時一般使用 ll::coro(如 ll::coro::keepThis([=]() -> ll::coro::CoroTask<> { co_await std::chrono::seconds(1); ... }).launch(ll::thread::ServerThreadExecutor::getDefault());),同樣要按值捕獲。

LeviLamina mod 中事件監聽崩潰,崩潰位置在 isCancelled() 附近,異常碼 0xC0000005,看起來像空指針,原因是什麼?

常見原因是用 EventIdView 構造事件 id 時傳入了臨時 std::string(如 fmt::format 的返回值):EventIdView 內部只持有 std::string_view,語句結束後臨時字符串被銷燬,view 懸空(UB,測試時不一定能復現)。解決:改為返回/持有 ll::event::EventId(它持有 std::string,可隱式轉換成 EventIdView),或保證源字符串的生命週期覆蓋使用期間。另外 0xC0000005 是 EXCEPTION_ACCESS_VIOLATION,不一定是空指針:ExceptionInformation[0] 為讀寫標誌(0 讀、1 寫、8 DEP),[1] 為不可訪問的地址;由於內聯優化,dmp 中定位的行可能偏到相鄰語句。

適用版本:LeviLamina 1.x 及以上(含 26.60.x)

LeviLamina mod 中寫 auto* bs = dynamic_cast<BedrockSpawner*>(&ll::service::getLevel()->getSpawner()); 導致崩潰(vcruntime140.dll 0xC0000005 訪問衝突),為什麼?

BDS(Windows 版)編譯時沒有可用的 RTTI 信息,對 BDS 內部類型使用 dynamic_cast 會失敗(返回 nullptr 或直接在 vcruntime 中崩潰)。getSpawner() 返回 Spawner&,取地址本身沒問題;應改用 static_cast:auto* bs = static_cast<BedrockSpawner*>(&ll::service::getLevel()->getSpawner());(需自行確保實際類型就是 BedrockSpawner)。

適用版本:LeviLamina 26.x(Windows BDS)。未能從源碼或文檔中直接證實,僅供參考。

hook 了某個 BDS 函數(例如活塞的紅石更新函數),參數是無效地址導致崩潰,而同類其他方塊的同名 hook 卻正常,為什麼?

檢查該函數在 LeviLamina 頭文件中是否標記為 MCFOLD。MCFOLD 表示該函數被編譯器做了相同 COMDAT 摺疊(Identical COMDAT Folding),其地址與其他函數共享,hook 它會同時攔截到多個不同函數的調用,參數可能根本不是預期類型。MCFOLD 函數仍可調用/hook,但 hook 時需要自行判斷調用來源(如檢查 this 的實際類型/方塊類型)和參數有效性(必要時可用 Windows API IsBadReadPtr 檢查指針可讀性);更好的做法是改 hook 一個未被摺疊的上層/下層函數。

把服務端 mod 移植到 LeviLamina 客戶端後,hook 裡的代碼運行異常/崩潰(異常在 MINECRAFT MAIN THREAD),怎麼處理?

一般是 hook 的點位在非 MC_SERVER 線程觸發了(客戶端還有主線程、渲染線程等)。絕大多數服務端側 MCAPI 只能在 MC_SERVER 線程調用,需要在 hook 中先判斷當前線程是否為服務端線程再執行服務端邏輯。可參考 LegacyScriptEngine 的 lse::api::thread::isServerThread():auto instance = ll::service::getServerInstance(); return instance && std::this_thread::get_id() == instance->mServerInstanceThread->get_id();,其事件實現(如 src/lse/events/BlockEvents.cpp)在回調中先 if (isServerThread()) 再處理。另外拿到的 BlockSource 可能屬於客戶端世界,應先用 blockSource.getLevel().isClientSide() 判斷(BlockSource 本身沒有 isClientSide(),需經 Level/ILevel),客戶端側的 BlockSource 不要做 removeBlock 等服務端操作(客戶端的 playerDestroy 也不會生成掉落物)。

適用版本:LeviLamina 客戶端版

自己編譯的 LeviLamina mod 在事件監聽中報錯(如 Error in Listener<ll::event::world::BlockChangedEvent>)而官方 tests 無法復現,應該檢查什麼?

先檢查 mod 是否使用了 LeviLamina 的內存分配器(mimalloc):官方模板在 src/mod/MemoryOperators.cpp 中 #include "ll/api/memory/MemoryOperators.h",缺少它會導致跨 DLL 分配/釋放不一致而崩潰。若仍有問題,刪除項目中的舊 .xmake 緩存目錄(以及 build 目錄)後重新 xmake f 配置並構建,避免舊依賴/舊頭文件殘留。