LeviLamina 模組 API:Hook 與內存
LeviLamina mod 的 disable/unload 裡需要手動 unhook 嗎?用 AUTO 宏註冊的 hook 會自動卸載嗎?
AUTO 系列宏(LL_AUTO_TYPE_INSTANCE_HOOK 等)會生成一個全局 HookRegistrar 對象,構造時 hook、析構時 unhook。因此 mod 被卸載(unload,DLL 被釋放,靜態對象析構)時這些 hook 會自動卸載,unload 中無需寫 unhook;但僅僅禁用(disable)不會釋放 DLL,hook 仍然生效。如果希望 disable 後 hook 不再起作用(支持熱重載/運行時禁用再啟用),需要在 disable 中調用 DEF_TYPE::unhook(),並在 enable 中調用 DEF_TYPE::hook()(或改用非 AUTO 的 hook 手動管理)。如果不打算支持熱重載,可以不寫這些代碼。另外所有 hook 都會在遊戲退出時自動卸載。
適用版本:LeviLamina 0.13 及以上
如何在 LeviLamina 中 hook 遊戲(BDS)函數?有沒有教程?
使用 LeviLamina 在 ll/api/memory/Hook.h 中提供的 hook 宏:LL_TYPE_INSTANCE_HOOK / LL_AUTO_TYPE_INSTANCE_HOOK(實例函數)、LL_TYPE_STATIC_HOOK / LL_AUTO_STATIC_HOOK(靜態函數)等,以及帶 _EX 後綴的變體。帶 AUTO 的宏會自動註冊;非 AUTO 的需要手動調用 XXXHook::hook() 註冊(並在卸載時 unhook())。官方教程:https://levimc.org/zh-Hant/LeviLamina/developer_guides/how_to_guides/hook_guide/(舊 lamina.levimc.org 鏈接會重定向),也可參考 LegacyScriptEngine 等官方 mod 源碼中的 hook 寫法。
適用版本:LeviLamina 當前版本
寫 LeviLamina hook 需要哪些信息?要 hook 的 BDS 函數聲明/符號去哪裡找?
一個 hook 需要:hook 名稱(DEF_TYPE)、優先級、所屬類型(TYPE)、目標函數標識(IDENTIFIER,通常寫成成員函數指針如 &ScreenView::render,或符號字符串)、返回類型和參數列表。
BDS 的類與函數聲明可在 LeviLamina 倉庫自帶的反編譯頭文件中查找:服務端/通用部分在 src/mc,僅客戶端的在 src-client/mc(https://github.com/LiteLDev/LeviLamina/tree/main/src/mc)。注意頭文件中標記為 MCNAPI 的函數當前不可用(未導出),無法直接引用,需要時到 https://github.com/LiteLDev/mcapi-requests 申請。
官方另有“查找函數”指南:https://levimc.org/zh-Hant/LeviLamina/developer_guides/how_to_guides/find_function_guide/。
適用版本:LeviLamina 當前版本
LeviLamina 頭文件中很多類的構造函數只有聲明沒有實現(編譯 mod 報缺少構造函數符號/提示不可用),mod 裡要構造這個類該怎麼做?能不能把虛表填 nullptr?
頭文件中標註 // prevent constructor by default 的那些只聲明不實現的構造函數,是統一用來防止意外構造的:原構造函數往往被內聯,無法確定其中是否有特殊邏輯,所以默認禁用;若連構造函數符號都沒有,也可能是被編譯器優化掉了。
需要構造時只能人工判斷後自己實現:在 mod 代碼中自行實現該構造函數,或把類聲明覆製出來自己定義/實現構造邏輯。若自己定義該類,應自行實現虛函數,不要把虛表填 nullptr,否則其他 mod hook 或直接調用虛函數時會崩潰。
另外 LeviLamina 受 Mojang 要求採用 API 白名單,缺少的符號(含構造函數)需要到 https://github.com/LiteLDev/mcapi-requests 提 issue 申請,維護者會在後續版本中加入(LL 的 CHANGELOG 中經常有“Added constructor for ...”這類更新)。
適用版本:LeviLamina 26.60.x
LeviLamina 沒有提供某些上層 API(如攔截原版網絡包、修改方塊渲染),事件系統裡也沒有網絡包事件,原生 mod 要怎麼實現?
LeviLamina 的上層 API 較少,缺的功能需要自己 hook 遊戲函數。LeviLamina 源碼中的 mc 目錄(src/mc、src-server/mc、src-client/mc)提供了 MC 的頭文件,可在其中查找對應的類和函數,再用 LL 的 hook 宏(如 LL_TYPE_INSTANCE_HOOK / LL_AUTO_TYPE_INSTANCE_HOOK)進行 hook。
攔截服務端收到的原版數據包:hook ServerNetworkHandler 中對應包類型的 handle(NetworkIdentifier const&, XxxPacket const&);客戶端側的包處理在 ClientNetworkHandler / LegacyClientNetworkHandler(src-client)。渲染相關修改(如連接紋理)可參考其他開源 mod 的渲染邏輯,在渲染時 hook 並替換材質。
適用版本:LeviLamina 當前版本(hook 目標隨 BDS 版本變化,需自行核對頭文件)
C++ mod 中使用帶 AUTO 的 hook 宏(如 LL_AUTO_TYPE_INSTANCE_HOOK)後,又手動調用了 hook(),導致回調被重複執行、出現異常,為什麼?
帶 AUTO 的 hook 宏會生成一個 inline 的 HookRegistrar 靜態對象,在 DLL 加載時自動執行一次 hook()。如果再手動調用一次 Hook::hook(),就會重複掛鉤,導致回調重複執行。用 AUTO 宏就不要再手動 hook();若想自己控制時機,使用不帶 AUTO 的宏(如 LL_TYPE_INSTANCE_HOOK)並手動調用 hook()/unhook(),或用 ll::memory::HookRegistrar<Hook1, Hook2...> 統一管理(它帶引用計數,不會重複掛鉤)。
適用版本:LeviLamina 1.x 及以上
C++ mod 開發中,只有 HopperBlockActor 時如何獲取漏斗指向的方塊(需要 BlockSource)?例如實現漏斗物品計數器。
可以參考 trapdoor 的做法:hook HopperBlockActor 的 tick(BlockSource& region),從參數中拿到 BlockSource 並臨時保存。漏斗是在 tick 過程中觸發 setItem(int slot, ItemStack const& item) 的,按調用順序,tick hook 中保存的 BlockSource 對應當前正在 setItem 的漏斗;再用 BlockActor::getPosition() 加上漏斗方塊的朝向(方塊狀態)算出它指向的方塊位置。
適用版本:LeviLamina(依賴 BDS 內部調用順序)。未能從源碼或文檔中直接證實,僅供參考。
LeviLamina C++ mod 中照抄 LL 源碼寫的 hook(如 LL_TYPE_INSTANCE_HOOK)編譯通過卻沒有任何效果,原因是什麼?AUTO 與非 AUTO 的 hook 有何區別,能否卸載?
hook 宏的第一個參數 DEF_TYPE 就是生成的結構體名,不能與 LeviLamina 內置 hook 或其它 hook 在同一命名空間下重名,改個名字即可。
帶 AUTO 的宏(如 LL_AUTO_TYPE_INSTANCE_HOOK)會在加載時自動調用 hook() 註冊;不帶 AUTO 的(如 LL_TYPE_INSTANCE_HOOK)需要自己調用 DEF_TYPE::hook() 註冊,否則不會生效。兩者都可以調用 DEF_TYPE::unhook() 卸載(所有 hook 也會在 Minecraft 卸載時自動卸載)。在 hook 體內不調用 origin(...) 即相當於攔截原函數(返回值非 void 時要返回合適的值)。參考 src/ll/api/memory/Hook.h 與官方 hook 指南。
LeviLamina 中 hook 一個成員函數用了 STATIC_HOOK,結果在日誌/調用處報錯崩潰,應該用哪種 hook 宏?
成員函數帶有 this 指針,應使用 INSTANCE_HOOK 系列(如 LL_TYPE_INSTANCE_HOOK / LL_AUTO_TYPE_INSTANCE_HOOK)而不是 STATIC_HOOK;STATIC_HOOK 系列只用於靜態/自由函數。詳見 LeviLamina 官方文檔站的 hook 指南(開發者指南 how_to_guides/hook_guide)。
適用版本:所有版本
LeviLamina 寫 hook 時,目標函數名帶 $ 前綴和不帶有什麼區別?
帶 $ 前綴的是虛函數的實現(如 &Player::$attack),hook 虛函數時必須使用帶 $ 的名字;非虛函數直接用普通名字(&ClassName::method)。例如 LL_TYPE_INSTANCE_HOOK(..., ServerNetworkHandler, &ServerNetworkHandler::$handle, ...)。
適用版本:所有版本
LeviLamina 是否支持通過特徵碼(signature)查找函數並 hook?還有哪些開發中常被忽略的功能?
支持。ll/api/memory/Signature.h 提供 SignatureView 及 "..."_sig / "..."_sigp 字面量(SignatureView::resolve() 解析地址),Hook 宏(LL_AUTO_TYPE_INSTANCE_HOOK 等)的函數標識既可以是符號/成員函數指針,也可以直接傳 SignatureView 特徵碼。
此外還有:
ll/api/memory/Memory.h裡的virtualCall(按虛表索引調用虛函數)ll/api/reflection(反射,可直接把結構體序列化為配置)ll/api/Config.h(ll::config::loadConfig/saveConfig基於反射讀寫 JSON 配置,無需自己解析)
這些功能文檔較少,可直接閱讀源碼。
適用版本:LeviLamina 1.x 及以上
LeviLamina 的 Hook 有優先級,如果高優先級的 Hook 直接 return 而不調用 origin,低優先級的 Hook 還會被觸發嗎?
不會。同一函數上的多個 Hook 按 HookPriority 形成調用鏈,優先級高的先執行(Highest=0 … Lowest=400),每個 Hook 內調用 origin(...) 才會進入下一個(更低優先級的)Hook,最終到達原函數。若高優先級 Hook 不調用 origin 直接返回,調用鏈就此中斷,低優先級 Hook 和原函數都不會執行。
適用版本:所有版本
LeviLamina 的 hook 宏(如 LL_AUTO_TYPE_INSTANCE_HOOK)寫在函數里報錯(括號後紅色波浪線),為什麼?
hook 宏本質上展開為一個結構體(類型)定義(含 inline static 成員、模板特化等),只能寫在命名空間/全局作用域,不能放在函數體內。應把宏放到函數外定義;非 AUTO 版本(LL_TYPE_INSTANCE_HOOK)可在需要時通過 Hook::hook() / unhook() 或 ll::memory::HookRegistrar 手動註冊。
適用版本:所有版本
在 LeviLamina mod 中實現樹葉快速腐爛時,hook/調用 Block 的 randomTick 虛函數對樹葉無效,為什麼?
樹葉的隨機刻邏輯不是通過 BlockType 的虛函數 randomTick 實現的:LeavesBlock 有自己的非虛成員函數 randomTick(BlockEvents::BlockRandomTickEvent&)(新版中隨機刻已改為事件形式,腐爛邏輯也已拆分)。需要把 BlockType static_cast 到 LeavesBlock,再調用或 hook 這個非虛的 LeavesBlock::randomTick。
適用版本:LeviLamina 當前版本
在 LeviLamina 中 hook 一個類的構造函數,返回值寫成 void 後運行報錯/崩服,構造函數的 hook 應該怎麼寫?
構造函數的 hook 應針對頭文件中的 thunk 函數 &Type::$ctor,返回值必須寫成指針(與 $ctor 聲明一致,現為 void*),並返回原函數的結果,因為構造完的對象地址通過返回值傳遞。寫成 void 會破壞返回值,導致崩潰。示例:
LL_AUTO_TYPE_INSTANCE_HOOK(DedicatedServerCtorHook, ll::memory::HookPriority::Normal,
DedicatedServer, &DedicatedServer::$ctor, void*) {
return origin();
}適用版本:LeviLamina 當前版本
在 LeviLamina 的 hook 宏(如 LL_TYPE_INSTANCE_HOOK 等)裡,TYPE 參數為什麼有時要用全局命名空間限定(寫成 ::ClassName)?
TYPE 是被 hook 函數所屬的類型,宏展開後會用於 TYPE::* 成員指針和繼承等。用 ::ClassName 形式(全局命名空間限定)可以避免與當前命名空間內的同名類型衝突(例如你的 mod 命名空間裡也有同名類)。一般不加也沒問題,出現名字衝突/解析錯誤時再加 ::。想弄清楚可以直接展開 hook 宏查看生成代碼(src/ll/api/memory/Hook.h)。示例:https://github.com/engsr6982/CustomWorldGenerator/blob/main/src/Hooks/structure.cpp
適用版本:LeviLamina 當前版本
開發 MCBE Windows 客戶端 mod 時,hook 了 WeatherManagerProxy::$getRainLevel、LevelRendererCamera::calcRainState 等函數並寫入 WeatherRenderObject.mDensityRain,卻看不到天氣變化。怎樣實現只在客戶端本地顯示的天氣?
可以 hook Weather::$levelEvent,先判斷當前是否為本地世界,再決定是否走原邏輯,例如:
if (auto client = ll::service::getClientInstance()) {
if (auto info = client->getGameConnectionInfo(); info && info->mType == Social::ConnectionType::Local) {
return origin(type, pos, data);
}
}注意:最新頭文件中 Weather::$levelEvent 標記為 MCNAPI(無導出符號),需要用特徵碼定位後再 hook。
適用版本:LeviLamina 客戶端(src-client)mod。未能從源碼或文檔中直接證實,僅供參考。
多個 LeviLamina 客戶端 mod(如回放、小地圖、BetterRenderDragon)hook 同一個函數產生衝突怎麼辦?
通過 LeviLamina 的 hook 宏(會在 hook 裡調用 origin 原函數)掛鉤同一函數時,一般可以共存;若某個 mod 用特徵碼掃描/直接改字節等方式,就可能因為函數開頭已被其他 hook 修改而衝突。可以調整加載順序,讓某個 mod 先加載:在 mod 的 manifest.json 裡使用 dependencies / optionalDependencies / loadBefore 等字段控制。同一函數上多個 hook 的執行先後也可以用 HookPriority 調整。
適用版本:LeviLamina 當前版本
如何在 LeviLamina 插件中檢測玩家簽名書本時的書名(例如書名為特定值時執行邏輯)?
書本編輯/簽名在客戶端完成後通過 BookEditPacket 發給服務端,可以 hook ServerNetworkHandler::$handle(NetworkIdentifier const&, BookEditPacket const&)。在最新版本中 BookEditPacket 繼承自 ll::PayloadPacket<BookEditPacketPayload>,payload 的 mOperation 是一個 std::variant(ReplacePage/AddPage/DeletePage/SwapPages/Finalize);簽名對應 BookEditAction::Finalize,其中 mTitle、mAuthor、mXuid 分別是書名、作者名和 xuid。頭文件:src/mc/network/packet/BookEditPacketPayload.h、src/mc/network/packet/book_edit_action/Finalize.h。
適用版本:LeviLamina 26.60.x
如何攔截玩家用南瓜頭搭建鐵傀儡?
hook BlockPatternMatcher::match(::BlockPos const& pos) const,判斷 this->mData(BlockPatternData const&,含 mPattern 圖案)是否為鐵傀儡的建造圖案;若是,把返回的 BuildMatch 的 mMatched 改為 false。注意該函數在最新頭文件中標記為 MCNAPI,需要用特徵碼定位。
適用版本:LeviLamina 當前版本
開發 LeviLamina mod 時,需要的函數被內聯了,或者是 MCFOLD(被合併的相同函數),該怎麼調用或 hook?
被內聯的函數只能找更底層的調用方式:getXxx 這類 getter 經常被內聯,有的變成直接訪問成員,有的需要通過別的方法拿到。MCFOLD 表示該函數與其他函數被編譯器做了相同代碼摺疊(Identical COMDAT Folding),多個函數共用同一份實現,所以 hook 它時必須在 hook 裡判斷調用來源。推薦檢查 this 的虛表指針,確認是目標類後再執行自己的邏輯。要弄清有哪些調用方,可以用 IDA 分析。
適用版本:LeviLamina 當前版本
想 hook 基岩版的日誌輸出函數來攔截遊戲日誌,hook 了某個函數卻輸出一堆亂七八糟的內容,該 hook 哪個函數?
hook 錯函數了(hook 到的是類似 Util::format/formatWide 的格式化函數,調用者極多)。應該和 LeviLamina 一樣 hook BedrockLogOut(聲明在 mc/common/Globals.h:void BedrockLogOut(uint const _priority, char const* pszFormat, ...)),可參考 LeviLamina 源碼 src/ll/core/tweak/ModifyInfomation.cpp 中的 BedrockLogOutHook(LL_STATIC_HOOK(BedrockLogOutHook, HookPriority::Normal, BedrockLogOut, void, uint priority, char const* pszFormat, ...))。
想在 LeviLamina mod 裡阻止活塞/移動方塊推動旁觀者模式玩家,應該 hook 哪個函數?為什麼攔截了服務端後移動方塊仍會推動玩家?
服務端活塞推動實體的邏輯最終都會走 PistonBlockActor::moveEntityLastProgress(PistonBlockActor::_moveCollidedEntities / _moveCollidedEntitiesHelper 也是這一路),可以在這裡攔截。但移動方塊(moving block)推動實體是客戶端也會自行判斷的行為:即使攔截多餘的 MoveDeltaActor 包、服務端活塞不再推動,移動方塊依舊能在客戶端推動玩家。要徹底解決只能改發包(例如只對旁觀者特判,改用直接 setBlock 等方式)。
適用版本:當前 LeviLamina 版本
想用 LeviLamina 監聽/攔截玩家做表情(emote),hook 了 Player 的虛函數 playEmote 卻從服務器啟動起就一直被循環調用,應該 hook 哪裡?
不要 hook Player::playEmote(服務端該虛函數槽只是佔位,不對應真正的表情處理)。應 hook ServerNetworkHandler::$handle(NetworkIdentifier const&, EmotePacket const&),在 hook 裡用 thisFor<NetEventCallback>()->_getServerPlayer(identifier, packet.mSenderSubId) 拿到對應玩家(寫法同 LeviLamina 的 PlayerChatEvent 實現)。要攔截時不調用 origin 直接 return 即可。服務端對該包的處理本質是轉發給其他玩家,所以攔截後只有發送者本地能看到動作。
適用版本:當前 LeviLamina 版本
新版 BDS 裡,原來在 ScriptActorEventListener 這類類裡 hook 的函數找不到了,該去哪裡找?
Mojang 每隔幾個版本就會把 Script****EventListener 裡的部分函數挪到對應的 Script****GlobalEventListener 裡,比如 ScriptActorEventListener 的函數被挪到了 ScriptActorGlobalEventListener。找不到時直接去對應的 Global 版本里找(目錄在 mc/scripting/modules/minecraft/events/)。
適用版本:BDS 26.40 及以後(LeviLamina 26.x)
新版 BDS(clang 編譯)裡,傳送門生成豬靈的函數 PortalBlock::trySpawnPigZombie 被內聯了,mod 想攔截或修改這段邏輯怎麼辦?
SpawnChecks::canSpawnPigZombieFromPortal 仍然可以 hook(MCAPI),但它拿不到座標;座標可以通過 hook PortalShape::evaluate 獲取。按維護者的建議,在 hook 裡先調用 origin,再接自己的實現(不要提前 return),因為這個函數後面緊接著就是原始實現。函數被內聯後,一般要改成同時 hook 兩個函數來實現。
適用版本:BDS 26.20+(LeviLamina 26.x)
新版 BDS 頭文件裡找不到 LevelChunk::tick,要 hook 區塊 tick 該用什麼?
這個函數改了,現在叫 LevelChunk::tickImpl(BlockSource& tickRegion, Tick const& tick, std::function<void()> spawnerCallback),比原來多了一個和刷怪相關的回調參數。改成 hook tickImpl,並按新簽名調整參數即可。如果函數被內聯或改名,也可以改為 hook 它的上層函數。
適用版本:BDS 1.21.6x 及以後(LeviLamina 26.x)
給 LeviLamina 提 PR 還原被內聯掉的函數(以 LLAPI 形式實現)時,如果該函數只在服務端存在、客戶端沒有(或兩端符號不同),應該怎麼處理?
客戶端和服務端的函數集合並不相同。對僅服務端需要的還原實現,用平臺宏包裹,例如 #ifdef LL_PLAT_S ... #endif(客戶端為 LL_PLAT_C),僅在服務端平臺編譯。手寫的聲明放在自動生成區塊之外,用 LLAPI/LLNDAPI 標註,定義放在同目錄 .cpp 中。若還原後確認正確,應刪除原來對應的 MCAPI 聲明;PR 修改直接推送到原分支即可,無需關閉 PR 重開。
適用版本:LeviLamina 當前版本(雙端構建)
能否只取消攻擊中的暴擊判定(其他邏輯不變),比如把原版暴擊改成純隨機暴擊率?
LSE 的攻擊事件只能攔截整次攻擊,無法單獨攔截暴擊(可攔截後自己處理減傷並用 hurt 造成傷害)。用 C++ 可以 hook Player::attack(Actor&, ActorDamageCause const&, Player::AttackParameters const&),把 parameters 裡的 mCanCrit 改為 false 即可不暴擊,再自行實現暴擊率(也可藉助 iListenAttentively 導出給 LSE 的接口)。
適用版本:LeviLamina 當前版本