LeviLamina 模組 API:線程、調度與生命週期
C++ mod 的 unload 應該怎麼寫?levilamina-mod-template 裡被註釋、帶 TODO 的 unload 需要取消註釋嗎?
模板裡的 unload() 默認被註釋,TODO 的意思是需要支持卸載時才自己實現。沒把握就保持註釋(不實現 unload),這樣 LeviLamina 會拒絕卸載該 mod(提示 The mod does not register an unload function),對正常運行沒有影響;也可以實現後直接 return false 拒絕卸載。若要支持 unload:卸載時 DLL 會被釋放,可能不執行 atexit 並強制結束線程,所以所有線程要用線程池並在析構時 join,不要使用需要清理的全局變量,把狀態都放在 mod 對象裡,在 unload 中自行釋放所有資源,否則會崩潰。事件監聽在禁用/卸載時由 LeviLamina 自動移除,命令會被自動禁用。
適用版本:LeviLamina 0.9 及以上(當前所有版本)
LeviLamina 有沒有直接獲取服務器 TPS/MSPT 的 API?想在 mod 裡常駐顯示 MSPT/TPS,需要自己 hook tick 嗎?怎麼算?
LeviLamina 沒有直接提供 TPS/MSPT API,但也不需要自己 hook tick。舊版的 ll::schedule(GameTickScheduler / ServerScheduler)已被移除,現在用協程:在服務器線程執行器 ll::thread::ServerThreadExecutor::getDefault() 上跑一個循環,每次 co_await 1_tick(ll::chrono::ticks)後記錄時間,相鄰兩次的時間差即 MSPT,TPS = 1000 / MSPT(超過 20 按 20 計);或者用全局 tick 計數器 + 另一個每秒執行一次的協程取差值得到每秒 tick 數。
協程用法可參考倉庫 src-test/common/ExecTest.cpp。BDS 自身也有計時數據,可參考 src/mc/profile/ProfilerLite.h 中的 ProfilerLite。也可使用第三方前置(如 GMLIB)的 TPS 接口。
適用版本:LeviLamina 1.x 至當前版本(26.60.x)
LeviLamina C++ mod 使用協程時,卸載/disable mod 導致服務端卡死或崩潰,如何正確停止協程、打斷協程裡的長時間 sleep?用 lambda 寫協程時 lambda 析構導致崩潰怎麼辦?
要保證 mod 卸載前協程都已結束。做法:
- 給 mod 單獨創建一個執行器(如
ll::thread::ThreadPoolExecutor),自己的協程都掛在它上面,disable 時銷燬它。 - 在協程循環中檢查停止標誌(如類成員
bool/std::atomic<bool>)以及ll::getGamingStatus(),每次co_await返回後檢查,需要停止就co_return。 - 長時間 sleep 用可打斷的等待:舊的
ll::coro::InterruptableSleep已移除,改用ll::coro::ConditionVariable(ll/api/coro/ConditionVariable.h)——把它放在類成員裡,協程中co_await cv.waitFor(时长, [&]{ return stop; }),disable 時置位標誌並調用cv.notifyAll()(確定在服務器線程上打斷服務器線程的協程時可傳inplace=true)。
注意 this 可能先於協程析構,可讓實現對象用 shared_ptr 並讓協程也持有一份。用 lambda 寫協程時,若 lambda 先析構協程會崩潰,可用 ll::coro::keepThis 把 lambda 拷貝進協程。另外 ll::coro::CallbackTransformer 可把回調轉為協程等待。
參考實現:https://github.com/GroupMountain/GMSidebar/blob/develop/src/Sidebar.cpp
適用版本:LeviLamina 26.60.0 及以上(ConditionVariable);keepThis、執行器、狀態檢查方案適用於 1.x 起所有版本
C++ mod 如何“可選依賴”另一個 mod(如 GMLIB):不直接鏈接它,存在時才調用其導出函數?為什麼 GetProcAddress 按函數名總取不到?LSE 腳本能調用嗎?
做法:導出方用 __declspec(dllexport) 導出函數;調用方運行時用 GetModuleHandleA 獲取對方模塊句柄(取不到即視為未安裝,跳過相關功能),再用 GetProcAddress 取函數指針。
C++ 函數有名稱修飾(name mangling,clang-cl 與 MSVC 使用同一套修飾規則),導出表裡的名字是 ?xxx@@... 這類修飾名,需要用 dumpbin /exports(或 llvm-objdump)查看完整修飾名傳給 GetProcAddress;若導出方由你自己控制,可用 extern "C" 導出避免修飾。不推薦用基址+RVA 硬編碼。正常開發更推薦直接引入對方的包調用。
LSE 腳本插件要調用 C++ 接口需要通過 RemoteCall(LegacyRemoteCall)等方式加依賴,不想加依賴只能讓對方執行命令(mc.runcmd)。
C++ mod 中在 load 階段調用 ll::service::getLevel() 然後 static_cast<ServerLevel&> 調用 getNewUniqueID(),出現 0xC0000005 空指針崩潰,如何正確獲取 Level?
Level 要等 BDS 讀完存檔後才存在,而 mod 的 load() 在打開存檔之前執行,此時 ll::service::getLevel() 返回空的 optional_ref。應先判斷 getLevel() 是否有值,並把相關邏輯放到 enable() 階段(或之後的事件)中執行:LeviLamina 在服務器線程啟動(ServerScriptManager::onServerThreadStarted)後才調用 enableAllMods,此時 Level 已就緒。
適用版本:當前版本(服務端)
C++ mod 中有異常連 try/catch 都攔不住(例如訪問違例),該怎麼捕獲?
訪問違例這類是 Windows SEH 結構化異常,catch (std::exception&) 之類的類型化 catch 捕獲不到。可靠的做法是用 __try/__except(MSVC 與 clang-cl 都支持;__try 所在函數里不要有需要析構展開的 C++ 對象,也不能與 C++ try 混用,可把危險調用包進一個單獨的小函數)。
注意:官方 mod 模板的 xmake.lua 雖然加了 /EHa,但它用 clang-cl 工具鏈,並且隨後又為 clang_cl 追加了 /EHs,所以不要指望 catch (...) 一定能接住 SEH 異常。對能被 catch 到的 C++ 異常,可以用 ll::error_utils::printCurrentException(logger)(ll/api/utils/ErrorUtils.h)打印。不過訪問違例通常說明代碼本身有問題,應修復根因,而不是靠捕獲繼續運行。
適用版本:Windows 平臺 LeviLamina mod(MSVC)
LeviLamina C++ mod 中 ll::memory::dAccess 怎麼用?怎麼按偏移取類成員(例如從 Minecraft 對象中拿 mSimTimer)?
dAccess 的模板參數填成員類型,第一個參數填對象地址,第二個參數填字節偏移:ll::memory::dAccess<T>(ptr, offset),返回 T&。注意 IDA 中顯示的 this+27 這類偏移若以 QWORD(8 字節)為單位,字節偏移要乘 8(27*8 = 0xD8);若該位置存的是指針,模板類型要寫成指針類型再解引用。偏移只能加一次,重複相加會導致 0xC0000005 訪問衝突。偏移與遊戲版本相關,不能跨版本照搬。
另外,當前 LeviLamina 頭文件中 Minecraft 已直接以 TypedStorage 形式聲明瞭成員 mSimTimer(Timer&),可直接通過 minecraft.mSimTimer 訪問而無需手算偏移;調整 tick 速率可用 Minecraft::setSimTimeScale,或直接改 Timer 的 mTimeScale。
適用版本:當前版本(偏移值隨遊戲版本變化)
LeviLamina C++ mod 中如何輸出日誌?std::cout 似乎沒有輸出。
服務端 std::cout / print / fmt::print 都能輸出,但推薦使用 mod 自己的 ll::io::Logger:
ll::io::Logger& logger = MyMod::getInstance().getSelf().getLogger();
logger.info("...");其中 MyMod 是你自己的 mod 主類(模板中 getSelf() 返回 ll::mod::NativeMod&)。客戶端需要開啟控制台(終端)窗口才能看到輸出。
LeviLamina C++ mod 中能否修改服務器 TPS(加速/減速/暫停遊戲刻)?
可以。Minecraft 對象內部有模擬計時器(mSimTimer,類型 Timer&,Timer 含 mTimeScale),並提供虛函數 setSimTimeScale(float scale) 和 setSimTimePause(bool pause),可用來加快、減慢和暫停遊戲刻,例如 ll::service::getMinecraft()->setSimTimeScale(2.0f);(getMinecraft() 返回 optional_ref<Minecraft>,使用前判斷有效)。
有用戶反饋原版對倍率有限制(約 0.1 倍到 10 倍),想突破需要自行修改 Timer 相關邏輯。也可以手動循環調用 ll::service::getLevel()->tick() 強制多跑 tick,但不推薦。
適用版本:當前版本(服務端)
LeviLamina C++ 插件如何支持熱卸載/重載?如何在 hook 函數外部取消 hook?
原生 mod 要支持熱卸載/重載(如 ll unload / ll reload),必須自己實現 unload:使用 LL_REGISTER_MOD 時在 mod 類中提供 bool unload() 即會被註冊,否則 LeviLamina 會報錯 The mod does not register an unload function,只能在關服時卸載。
用 LL_AUTO_TYPE_INSTANCE_HOOK 等 hook 宏時會定義一個 hook 類名,在 unload(或 disable)中直接調用該類的 unhook()(如 MyHook::unhook())即可在函數外取消 hook;非 AUTO 的宏需要手動調用 MyHook::hook() / MyHook::unhook()。此外智能指針、new 出來的內存、std::function、線程、事件監聽等的生命週期都要在 unload 中處理乾淨,否則卸載會崩潰;不會處理就不要寫 unload。
LeviLamina C++ 插件必須定義 load/enable/disable/unload 這幾個函數嗎?DllMain 還能用嗎?
當前版本使用 LL_REGISTER_MOD(类, 实例) 註冊時,只有 bool load() 是必須的(有 static_assert 檢查);enable、disable、unload 都是可選的,提供了才會被註冊。沒有 disable 時禁用會直接成功;沒有 unload 時該 mod 不能被熱卸載(ll unload / reload 會報 The mod does not register an unload function),只能隨關服卸載,而且除非很熟悉 C++ 生命週期管理,否則別寫 unload。
DllMain 仍會被調用但不建議使用,因為時機太早:DllMain 階段 LL API 不保證可用,load 階段遊戲 API 不保證可用,enable 階段兩者才都可用。作為 LL mod 應以 load 為入口點,否則就相當於 PreLoader 插件了。
LeviLamina mod 中不用 getSelf().getLogger() 的話,怎麼創建一個 logger?
當前版本 ll::io::Logger 的構造函數是私有的(PrivateTag),不能再直接 ll::Logger logger("MyMod"); 構造。應通過日誌註冊表獲取/創建:
auto logger = ll::io::LoggerRegistry::getInstance().getOrCreate("MyMod");它返回 std::shared_ptr<ll::io::Logger>,之後用 logger->info("...") 輸出。也可以繼續用 getSelf().getLogger()(返回 ll::io::Logger&)。
適用版本:LeviLamina 1.x 及以上
LeviLamina mod 中有一個涉及文件操作、不希望被拷貝的全局對象,把它傳給 cmd.overload().execute(lambda) 和 eventBus.emplaceListener<Event>(lambda) 的 lambda 使用時,需要用 std::ref 嗎?
不需要。全局(靜態存儲期)對象在 lambda 裡可直接使用,無需捕獲;局部對象可用引用捕獲 [&obj],都不會產生拷貝。std::ref 不是用於 lambda 捕獲的工具。只需保證對象生命週期長於回調(命令/監聽器存在期間)即可。可通過把拷貝構造設為 delete/private 驗證確實沒有拷貝。這是 C++ 語言規則,與 LeviLamina 版本無關。
適用版本:所有版本
LeviLamina native mod 中 load、enable、disable、unload 這幾個生命週期函數的調用順序和區別是什麼?
調用順序為 load -> enable -> disable -> unload。用 LL_REGISTER_MOD 註冊的 mod 類只有 load() 是必須實現的(bool load()),enable/disable/unload 都是可選的(實現了才會綁定)。服務器已在運行時加載 mod,load 成功後會立即調用 enable;熱卸載(unload)時會先調用 disable,再調用 unload。當前版本為 v26.60.8。
適用版本:LeviLamina 1.x 及以上
LeviLamina 模組中用 logger 輸出時如何拼接參數?
LeviLamina 的 logger(ll::io::Logger)的 info/warn/error/debug 等都支持 fmt 風格格式化,可直接寫 getSelf().getLogger().info("检查到玩家 {} 加入服务器!", ev.self().getRealName());,無需手動拼接字符串。變量可以用 auto 推斷,如 auto& player = ev.self();。
適用版本:LeviLamina 1.x 及以上
LeviLamina 的 logger.info 輸出包含換行符的多行文本時,後續行沒有時間前綴,該怎麼處理?
Logger 每次調用只格式化一條消息,按模式在整條消息前加一次時間/級別/標題前綴,字符串內部的換行不會補前綴。需要每行都有前綴時,先按行拆分(例如 std::istringstream + std::getline,或 ll::string_utils::splitByPattern)再逐行調用 logger.info。適用於 ll::io::Logger。
適用版本:所有版本
LeviLamina 的協程能利用多核 CPU 嗎?
可以。協程本身不決定在哪個線程執行,由啟動或恢復它的 Executor 決定。LeviLamina 提供了 ll::thread::ThreadPoolExecutor(繼承 ll::coro::Executor,可指定線程數,也有 ThreadPoolExecutor::getDefault()),通過 task.launch(executor) 把 ll::coro::CoroTask 放到線程池上執行即可利用多核。需要回到主線程操作遊戲對象時,使用 ll::thread::ServerThreadExecutor。注意 BDS 的遊戲 API 大多不是線程安全的。
適用版本:LeviLamina 1.x 及以上
一個 mod DLL 同時用於客戶端和服務端時,如何判斷當前是在客戶端還是服務端加載?
用 ll/api/Versions.h 中的 ll::isClient() 判斷 mod 是被客戶端還是服務端加載。
若在客戶端裡還需區分是本地世界(房主,內置服務端在運行)還是作為普通玩家進入遠程服務器:Level::isClientSide 不可靠,可以用 ll::service::getMinecraft()(默認取服務端實例,isClientSide=false)或 ll::service::getServerInstance()。能拿到即存在本地服務端邏輯,拿不到則只是客戶端連接遠程服務器。
適用版本:LeviLamina 1.9 及以上(含客戶端支持的版本)
使用 LeviLamina 的協程(ll::coro)時,co_await 1s 竟然讓主線程阻塞了一秒,是怎麼回事?應該如何正確啟動協程?
原因是用了 syncLaunch(照抄了 test 代碼)。syncLaunch 會在當前線程上阻塞等待協程結束並返回結果。
正常啟動協程用 CoroTask::launch(executor) 即可,它是異步的;launch 還有帶回調的重載 launch(executor, callback) 用於獲取返回值(無回調版本默認傳 [](auto&&){})。只有確實需要同步等待結果時才用 syncLaunch。
適用版本:LeviLamina 1.0 及以上
在 C++ mod 中使用延遲任務(定時/延遲執行)時,回調 lambda 不執行或行為異常,可能是什麼原因?
檢查 lambda 的捕獲方式:延遲任務會在之後才執行,若用引用捕獲 [&] 捕獲了局部變量,執行時這些變量已經銷燬,形成懸垂引用導致行為異常。改為值捕獲([=] 或顯式按值捕獲,必要時用 shared_ptr / weak_ptr 保活或判斷對象是否仍存在)即可。
當前 LeviLamina 推薦用協程實現延遲任務,例如:
ll::coro::keepThis([player = ...]() -> ll::coro::CoroTask<> {
co_await 20_tick; // 或 co_await 1s;
// ...
}).launch(ll::thread::ServerThreadExecutor::getDefault());同樣要注意 lambda 捕獲的對象在 co_await 之後是否仍然有效(例如玩家可能已下線)。
適用版本:當前所有 LeviLamina 版本(舊的 schedule/DelayTask API 已被 ll::coro 取代)
在 LeviLamina 原生 C++ mod 裡使用 cpp-httplib 啟動 HTTP 服務(listen 0.0.0.0)後,玩家無法連接服務器、連 MOTD 都沒有了,為什麼?
因為在主線程調用了 listen。httplib::Server::listen 是阻塞調用,會卡住 BDS 主線程,導致服務器無法響應。應在單獨線程(如 std::thread)裡運行 server.listen,並在 mod disable/卸載時調用 server.stop() 並 join 線程;不要在主線程 listen。
照著 LeviLamina 官網指南複製示例代碼寫 mod,用 self 時編譯報錯,怎麼改?
舊版指南里的 self 寫法已經過時。請按當前模板的寫法:MyMod 類在構造時保存 ll::mod::NativeMod::current() 返回的實例(成員 mSelf),再通過 getSelf() 取用,例如 MyMod::getInstance().getSelf().getLogger().info("...")。最省事的辦法是直接用 levilamina-mod-template 新建項目。
適用版本:LeviLamina 1.x 及以上
服務器上某個(可能閉源的)mod 一直往控制台刷日誌,能不能不改它的源碼就屏蔽或過濾掉?LeviLamina 會內置這種功能嗎?
LeviLamina 官方不會內置這種過濾(會有性能損失),需要自己寫 mod 來做。當前日誌系統下的做法:用 ll::mod::ModManagerRegistry::getInstance().getMod("mod名") 拿到該 mod,再通過它的 getLogger() 拿到 logger;如果對方是自己創建的 logger,就用 ll::io::LoggerRegistry::getInstance().tryGet("logger 标题") 獲取。拿到 ll::io::Logger 後,可以 setLevel(...) 提高輸出等級,也可以用 setSink / removeSink / clearSinks 替換或去掉它的 sink(比如換成自己實現的、帶過濾的 sink)。舊日誌系統裡 hook ll::OutputStream::print 的辦法已經不能用了。
適用版本:LeviLamina 1.x 及以上(新日誌系統 ll::io::Logger)
自己寫的第三方 mod 加載器(如 .NET loader)註冊的 mod,用 LeviLamina 的查詢 API 獲取不到,怎麼辦?
只要按標準方式註冊就都能獲取到。實現一個繼承 ll::mod::ModManager 的管理器並通過 ModManagerRegistry::addManager 註冊;在 load 時調用 addMod(name, mod) 把 Mod 對象加入管理器,unload 時調用 eraseMod(name)。ModManager 才是 Mod 對象的所有者,LeviLamina 不會自動幫你管理。可參照 LeviLamina 自帶的 NativeModManager 實現。之後即可通過 ModManagerRegistry::getManagerForMod / ModManager::getMod 等查詢到。
適用版本:LeviLamina 1.x 及以上(Plugin 已更名為 Mod)