跳到正文
本頁目錄

LeviLamina 模組 API:事件

LeviLamina C++ mod 中如何定義併發布自定義事件,讓其他 mod 的監聽器收到?(另:讀寫配置文件用哪個頭文件?)

定義一個繼承 ll::event::Event 的類,且必須聲明為 final(EventBus::publish 有 static_assert 要求 final 類),例如 class MyCustomEvent final : public ll::event::Event { ... };。需要廣播時構造事件對象併發布:ll::event::EventBus::getInstance().publish(ev);(也可用 publish(modName, ev) 只發給指定 mod)。其他 mod 通過 EventBus::getInstance().emplaceListener<MyCustomEvent>(回调) 或 addListener 監聽;如需在首次被監聽時才掛 hook,可配合 ll/api/event/Emitter.h 的 Emitter 實現懶加載發射器。配置文件讀寫可使用 ll/api/Config.h 中的 ll::config::loadConfig / saveConfig。

適用版本:LeviLamina 1.x 及以上(當前 v26.60.8)

LeviLamina 有沒有玩家“預加入”(連接服務器、早於進入世界/PlayerJoinEvent)的事件可以監聽?

有,使用 PlayerConnectEvent(ll::event::PlayerConnectEvent),它在 PlayerJoinEvent 之前觸發、可取消,能拿到 networkIdentifier() 和 connectionRequest()。需要 #include "ll/api/event/player/PlayerConnectEvent.h",再通過 ll::event::EventBus::getInstance().emplaceListener<ll::event::PlayerConnectEvent>(...) 訂閱。

適用版本:LeviLamina 0.4 及以上至當前版本(服務端)

BDS 遊戲主循環對應哪個類的 tick 函數?GameSession 裡找不到 tick()。

世界的 tick 在 Level/ServerLevel 上(Level::tick 為虛函數,hook 需用 $tick)。更簡單的做法是直接監聽 LeviLamina 自帶的 ll::event::ServerLevelTickEvent(頭文件 ll/api/event/world/ServerLevelTickEvent.h),它在當前版本是 hook ServerLevel::$_subTick 實現的。也可以用 LeviLamina 的調度器/GameChrono 做按 tick 定時任務。

適用版本:LeviLamina 26.x

C++ mod 中監聽服務器啟動事件時報錯(clangd 也報錯),文檔裡沒寫需要 include 什麼,怎麼辦?

需要包含 EventBus 的頭文件和對應事件的頭文件:

cpp
#include "ll/api/event/EventBus.h"
#include "ll/api/event/server/ServerStartedEvent.h"

然後在 mod 主類的 load/enable 等函數中通過 ll::event::EventBus::getInstance().emplaceListener<ll::event::ServerStartedEvent>(...) 訂閱(保存返回的 listener 以便 disable 時移除)。其他事件頭文件位於 ll/api/event/ 下按類別劃分的子目錄(server、player、entity、world、command 等)。

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

LeviLamina C++ mod 中如何攔截(取消)一個事件?

對可取消事件(繼承自 ll::event::Cancellable<...> 的事件,如 PlayerChatEvent、ExecutingCommandEvent 等),在監聽回調中調用 event.cancel()(等價於 setCancelled(true))即可攔截。不可取消的事件沒有該方法。

LeviLamina C++ mod 中想監聽玩家執行命令,參照 LLSE 的寫法監聽器觸發不了,應該監聽哪個事件?

說明監聽的事件類型不對。命令相關應監聽 ll::event::ExecutingCommandEvent(執行前,可 cancel 攔截)或 ExecutedCommandEvent(執行後),定義在 ll/api/event/command/ExecuteCommandEvent.h,通過 ll::event::EventBus::getInstance().emplaceListener<...>(...) 註冊。具體可參考官方文檔的事件 API 與事件指南。

LeviLamina C++ 插件如何監聽玩家釣魚事件?

LeviLamina 本體至今沒有釣魚事件(ll/api/event 下沒有相關事件),此前提到的 more-events 也沒有作為 LiteLDev 項目發佈,iListenAttentively 目前同樣未提供釣魚事件。需要自己 hook 相關函數實現,可參考 LegacyScriptEngine 的做法:用 LL_TYPE_INSTANCE_HOOK hook FishingHook::_pullCloser(Actor& inEntity, float inSpeed),通過 this->getPlayerOwner() 拿到釣魚的玩家,被拉起的實體若為 ItemActor 即釣到的物品(LSE 中對應 onPlayerPullFishingHook 事件)。

LeviLamina mod 中監聽兩個不同事件時,是否需要分別定義/獲取兩次 EventBus?

不需要。EventBus 是單例,使用同一個 ll::event::EventBus::getInstance() 分別對兩個事件調用 emplaceListener<EventA>(...) 和 emplaceListener<EventB>(...) 即可,並保存返回的 ListenerPtr 以便在 disable 時 removeListener。

適用版本:所有版本

LeviLamina 中直接銷燬自己持有的 ListenerPtr 而不調用 EventBus 的 removeListener,會有問題嗎?

不會有問題。ListenerPtr 是 std::shared_ptr<ListenerBase>,EventBus 內部也持有一份引用,所以銷燬自己手裡的 ListenerPtr 不會導致崩潰或懸垂指針。但要注意:這並不會註銷監聽器,監聽器仍會繼續收到事件;如需停止監聽應調用 EventBus::getInstance().removeListener(listener)。模組卸載時 EventBus 會通過 removeModListeners / clearMod 清理該模組的監聽器。

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

LeviLamina 事件系統中,高優先級監聽器取消(cancel)了事件後,低優先級監聽器還會收到事件嗎?

不會。早期設計中被取消的事件仍會派發給後續監聽器,需要監聽器自己判斷 isCancelled();後來維護者修改了行為:事件一旦被 cancel(),EventBus 立即停止派發,後續監聽器(包括同優先級中排在後面的監聽器)都不會再收到該事件。這樣保證只有一個監聽器負責攔截,避免大家都搶最高優先級。

適用版本:LeviLamina 1.2 之後

LeviLamina 插件裡註冊了事件監聽但事件不觸發,可能是什麼原因?事件 hook 是自動安裝的嗎?

可以按以下幾點排查:

  1. 注意註冊時機:服務端的 mod enable 階段是在服務器線程啟動(ServerScriptManager::onServerThreadStarted)時由 ModRegistrar::enableAllMods() 統一調用的,在此之前已經發生的事件(如更早的啟動階段事件)自然收不到。
  2. 事件的 hook 不是 auto hook:每個事件的 Emitter 是按需創建的,只有當該事件存在監聽者(EventBus::getInstance().emplaceListener<T>(...) / addListener)時才會安裝對應 hook。
  3. ll::event::player、ll::event::world 等子命名空間是 inline namespace,可以直接寫 ll::event::PlayerJoinEvent,無需寫 ll::event::player:: 前綴。
  4. 排查時可在回調裡用 logger 打日誌確認是否觸發。

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

LeviLamina 的 PlayerSwingEvent(swing 事件)指的是什麼動作?是鞘翅滑翔嗎?

不是滑翔。swing 指玩家揮手(揮動手臂)的動作:服務端收到客戶端 AnimatePacket 且 action 為 Swing 時觸發,交互容器、左鍵點擊、用斧頭去樹皮、攻擊等都會引起揮手。該事件 PlayerSwingEvent 繼承自 PlayerLeftClickEvent。

適用版本:所有版本

LeviLamina 的事件監聽能否指定優先級?例如聊天翻譯類插件如何避免與其他聊天插件衝突?

可以。創建 Listener 時可傳入 ll::event::EventPriority(Highest/High/Normal/Low/Lowest,默認 Normal),例如 EventBus::getInstance().emplaceListener<PlayerChatEvent>(callback, EventPriority::High)。優先級高的監聽器先處理事件,可藉此先於普通聊天插件處理/修改消息。一般不建議隨意使用 Highest,以免與其他插件產生兼容性問題。

適用版本:所有版本

PlayerUseItemEvent 在玩家剛右鍵使用物品(如開始吃麵包)時就觸發,即使沒吃完;怎樣只在物品真正使用完成(吃下去)後觸發?

LeviLamina 的 PlayerUseItemEvent hook 的是 PlayerTransactionSubject::$baseUseItem,即開始使用時觸發。要在使用完成時處理,應改用 Player::completeUsingItem 對應的事件:iListenAttentively(ila)提供 PlayerAteBeforeEvent / PlayerAteAfterEvent(hook Player::completeUsingItem,僅對食物、藥水、牛奶桶、藥品觸發,Before 可取消)。

如果需要覆蓋其它物品,可以自己用 LL_TYPE_INSTANCE_HOOK hook Player::completeUsingItem。

適用版本:LeviLamina 當前版本;iListenAttentively

在 LeviLamina mod 中想修改聊天消息格式(如在玩家名前加前綴),用 LL 的聊天事件能做到嗎?

LL 的 PlayerChatEvent 只提供 message() 用於修改實際聊天內容,不能改格式:發出的 TextPacket 類型是 Chat,顯示格式由客戶端寫死;要在玩家名前加內容,必須改用別的類型(如 TextPacketType::Raw)。

實現思路:攔截原版 TextPacket 的處理 handler 後自己發包(LSE 的做法),或 hook TextPacket 的 write,或攔截修改發給客戶端的 TextPacket。若需每個玩家顯示不同(如多語言),需攔截後為每個玩家單獨發包。

適用版本:LeviLamina 當前版本

在 LeviLamina mod 中處理 PlayerDieEvent / ActorHurtEvent / MobDieEvent 獲取傷害來源實體時,用 getDimension().fetchEntity() 或 Level::getDimension() 導致崩服(拿到 nullptr),應該怎麼寫?

實體 ID(ActorUniqueID)是全局的,沒必要先取維度,直接用 Level::fetchEntity(id, false) 獲取傷害來源實體即可(返回 Actor*,仍需判空)。

Level::getDimension(dimId) 返回 WeakRef<Dimension>,可能為空,使用前必須 lock() 並判斷,否則會崩;也可改用 getOrCreateDimension(dimId),只要 dimensionId 合法就能拿到維度。如果只需要實體所在維度 ID,直接用 actor.getDimensionId()。

不建議參考 LSE 中這幾個事件的寫法,建議參考 LeviLamina 本體或 LeviOptimize 等項目。

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

在 LeviLamina 中想實現“玩家編輯告示牌”事件並區分正反面,告示牌編輯後客戶端發給服務端的是什麼數據?有哪些實現思路?

打開告示牌編輯界面由服務端發送 OpenSignPacket(SignBlockActor::requestToSendOpenSignPacket(..., bool isFrontSide));編輯完成後客戶端發給服務端的是方塊實體數據包 BlockActorDataPacket(攜帶告示牌的 NBT)。

推薦實現思路:hook ServerNetworkHandler::$handle(NetworkIdentifier const&, std::shared_ptr<BlockActorDataPacket>)(MCAPI,可直接 hook),從中拿到發包玩家並解析 NBT,判斷改了哪一面、改成什麼內容。

另一思路是 hook BlockActor::onUpdatePacket(CompoundTag const&, BlockSource&, Player const* fromPlayer) 或 SignBlockActor::_onUpdatePacket,但當前頭文件中它們(onUpdatePacket、$_onUpdatePacket)被標為 MCNAPI("This API is not available"),無法直接按符號 hook,需要自行處理或向 LeviLamina 提 issue。

正反面相關成員在當前頭文件中已補全:SignBlockActor 有 mTextFront / mTextBack,getMessage(SignTextSide side)、getSideFacingPlayer(Player const&),SignTextSide 枚舉為 Front=0 / Back=1。

適用版本:LeviLamina 當前版本(26.x)

開發 LeviLamina 插件時,如何替換挖掘方塊的掉落物(例如挖泥土/三廢石改為掉落圓石)?生成的掉落物不會向上彈出怎麼辦?

監聽並攔截方塊破壞事件(ll::event::PlayerDestroyBlockEvent,可取消,pos() 拿到方塊座標),取消原掉落後,自己在該位置生成圓石掉落物即可(例如用 Spawner::spawnItem),可參考 CoralFans 的“基岩掉落”功能。如果掉落物沒有正常彈出(被方塊擠住),應先生成掉落物再移除方塊。注意要挖的方塊類型要對(草方塊和泥土是不同方塊)。原版掉落由專門的類處理,直接改 resourceDrops 對原版方塊不一定生效。

適用版本:LeviLamina 當前版本

想實現玩家死亡後藥水效果不掉,在玩家重生事件裡給玩家添加效果,代碼執行了但效果沒生效,重生那一刻不能添加效果嗎?

重生時原版邏輯會清理效果,直接在 PlayerRespawnEvent 裡添加會被覆蓋。解決辦法:延遲 1 tick 再添加效果;或者自己 hook Player::$respawn,先調用 origin 再執行添加效果的邏輯;也可以 hook 清除效果的函數,阻止死亡/重生時清除。

適用版本:當前 LeviLamina 版本

照著 LeviLamina 文檔寫玩家加入事件監聽,編譯時提示找不到事件類型,怎麼辦?

LeviLamina 的每個事件都放在單獨的頭文件裡,用到哪個事件就要 #include 哪個頭文件,只引入 EventBus 是不夠的。例如:

cpp
#include "ll/api/event/player/PlayerJoinEvent.h"

ll::event::EventBus::getInstance().emplaceListener<ll::event::PlayerJoinEvent>([](ll::event::PlayerJoinEvent& ev){ /* ... */ });

(player 是 inline namespace,寫 ll::event::PlayerJoinEvent 或 ll::event::player::PlayerJoinEvent 都可以。)另外改完代碼要先保存再編譯。

適用版本:所有 LeviLamina 版本

能否用 LeviLamina 的反射(ll::reflection)自動序列化/註冊各種事件類(例如為日誌插件自動記錄所有事件)?

不行。LL 的反射只支持聚合類型,不支持帶構造函數的類,事件類有構造函數,無法直接反射。事件自帶的 serialize(CompoundTag&) 也不是為持久化記錄設計的。只能自己寫模板,針對每個事件手動特化。

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