跳到正文
本頁目錄

事件與鉤子

模組有兩種方式對遊戲中發生的事情作出反應:鉤住(hook)遊戲的某個函數,或者監聽 LeviLamina 發佈的事件。 本頁說明這兩者如何工作以及它們之間的關係。如何使用它們見如何做到系列:鉤子指南和 事件指南;API 見 Memory & Hook(內存與鉤子)和 Event(事件系統)頁面。

鉤子

鉤子用模組中的一個函數——detour——替換遊戲的一個函數。遊戲調用該函數時,運行的是你的 detour;它調用 origin(...) 來運行原函數,並且可以修改參數、修改結果,或者根本不調用原函數。要鉤住的函數可以通過遊戲頭文件(mc/)中的函數指針、符號、 地址或特徵碼指定。

多個模組可以鉤住同一個函數。它們的 detour 按 HookPriority(Highest、High、Normal、Low、Lowest)組成一條鏈: 每次 origin(...) 調用下一個 detour,最後一個調用遊戲的函數。

鉤子只在安裝後才生效:

  • 用 LL_AUTO_ 宏聲明的鉤子作為 DLL 的靜態對象,在 DLL 加載時、模組的 load() 運行之前安裝。
  • 其他鉤子由它的 hook() 安裝,由 unhook() 移除。ll::memory::HookRegistrar<Hooks...> 對象在創建時安裝其中的鉤子, 在銷燬時移除它們;被多個 registrar 持有的鉤子會一直保持安裝,直到最後一個 registrar 被銷燬。

事件

事件是描述發生了什麼事情的對象,例如 PlayerJoinEvent。所有事件都經過同一個 EventBus:

  • 發佈。 知道事情發生了的代碼創建事件並調用 EventBus::publish。事件總線在發佈它的線程上逐個調用該事件類型的監聽器。
  • 監聽。 監聽器是針對一種事件類型、帶有 EventPriority 的回調。監聽器按從 Highest 到 Lowest 的順序被調用; 優先級相同的監聽器按創建的先後順序調用。
  • 取消。 派生自 Cancellable 的事件可以被監聽器取消。此時事件總線不再調用後面的監聽器,取消意味著什麼由發佈者決定: 例如被取消的 PlayerAttackEvent 會阻止這次攻擊。哪些內置事件可以取消,見 Event(事件系統)頁面中的“內置事件”。
  • 錯誤。 監聽器拋出的異常會被捕獲,並連同其所屬模組的名稱記入日誌;下一個監聽器照常運行。

事件如何使用鉤子

大多數內置事件是由鉤子發佈的。例如 PlayerAttackEvent 由 Player::attack 上的一個鉤子發佈:detour 發佈該事件, 如果有監聽器取消了它,就不調用原函數直接返回(參見事件指南中的“發佈事件”)。

這些鉤子並不是一直安裝著的。每種事件類型都有一個發射器(emitter),它是持有該事件鉤子的類(放在一個 HookRegistrar 中)。 LeviLamina 在添加該事件的第一個監聽器時創建發射器,在移除最後一個監聽器時銷燬它,同時移除它的鉤子。 沒有人通過事件監聽的遊戲函數不會被鉤住。

模組也可以用同樣的方式提供自己的事件:一個事件類(必須是 final)、一個發射器,以及發佈它的鉤子或代碼。

監聽器屬於模組

每個監聽器都屬於一個模組:默認是創建它的代碼所在的模組(NativeMod::current())。LeviLamina 藉此在模組之後進行清理:

  • 模組在遊戲運行時被禁用時,它的監聽器會被移除。
  • 模組被卸載時,它的監聽器會被移除,它提供的事件也會連同其他模組在這些事件上的監聽器一起被移除。

這就是模組在 enable() 中添加監聽器的原因:禁用時它們會被移除,再次啟用時會被重新添加。參見模組生命週期。

EventBus::publish(modName, event) 只調用屬於模組 modName 的監聽器。

用鉤子還是事件?

  • 如果有對應的事件,就用事件:它與其他所有模組共享,只在有人監聽時才安裝,並且會隨你的模組一起被移除。
  • 沒有事件覆蓋的情況再用鉤子。用找函數指南找到函數, 除非有理由,否則把優先級保持為 Normal。

相關文檔