模組生命週期
本頁說明 LeviLamina 如何找到服務器或客戶端的模組、按什麼順序加載它們,以及何時調用模組的 load、enable、
disable 和 unload。這裡提到的類和字段都列在 Mod(模組系統)頁面上。
四個步驟
模組會經歷四個步驟。每一步都會調用模組的一個回調;回調返回 false 時這一步就會中止,LeviLamina 會在日誌中寫明原因。
| 步驟 | 發生時機 | 回調 | 之後 |
|---|---|---|---|
| 加載 | 啟動時,對每個應當運行的模組;運行時通過 /ll load |
load() |
模組已加載,處於禁用狀態 |
| 啟用 | 遊戲啟動完成時;如果遊戲已在運行,則在加載後立即啟用 | enable() |
模組已啟用 |
| 禁用 | 遊戲停止時;運行時通過 /ll disable |
disable() |
模組已禁用,但仍處於加載狀態 |
| 卸載 | 僅在運行時,通過 /ll unload 或 /ll reload |
unload() |
模組被移除,其 DLL 被釋放 |
模組要麼是 Enabled(已啟用),要麼是 Disabled(已禁用)(Mod::State):剛加載的模組在啟用之前處於禁用狀態。
遊戲停止時,模組會被禁用,而不會被卸載。
使用 LL_REGISTER_MOD(Class, instance)(參見 Mod(模組系統)中的“註冊模組入口”)時,
load() 是必需的,enable()、disable() 和 unload() 在類定義了它們時才會被使用。沒有 unload() 的原生模組無法在運行時卸載:
LeviLamina 會以“The mod does not register an unload function”拒絕。
查找模組
啟動時,LeviLamina 會查看模組根目錄中的每個文件夾:服務端為 plugins/,客戶端為 mods/(參見
Mod(模組系統)中的“目錄結構”)。
- 沒有
manifest.json或其內容為空的文件夾會被跳過。 - 清單中的
name必須與文件夾名相同,否則不會加載該模組(“Mod name … do not match folder …”)。 - 類型為
preload-native的清單會被跳過:它們由 PreLoader 在遊戲啟動之前加載,不屬於 LeviLamina 模組(參見 Mod(模組系統)中的“模組類型”)。
選擇與排序
LeviLamina 在加載任何模組之前,先根據清單制定一個計劃:
- 加載哪些模組。 從每個不是
passive的模組出發,加上它們需要的模組:它們的dependencies,以及已安裝且版本匹配的optionalDependencies。passive模組只在某個會被加載的模組依賴它時才會被加載。 - 其中哪些不能運行。 以下情況的模組會被排除:缺少某個依賴,或依賴的版本不在它要求的範圍內;它的
platform不是當前平臺 (server或client;universal或未寫platform則兩端都可運行);它在conflicts中列出了計劃中的另一個版本匹配的模組; 它的某個依賴被排除;或者它處於依賴環中。日誌會寫明原因,例如“… will not be loaded because it conflicts with …”。 - 按什麼順序。 依賴和可選依賴排在使用它們的模組之前;聲明瞭
loadBefore的模組排在它列出的模組之前。 相互之間沒有順序要求的模組按名稱排序。
然後按這個順序逐個加載模組。依賴加載失敗的模組也會被跳過。
加載
在服務端,LeviLamina 在遊戲的 main 開始時、遊戲本身運行之前加載模組;在客戶端,則是在 PreLoader 把 LeviLamina
加載進遊戲時。此時遊戲、它的世界和玩家都還不存在。
模組的 type 決定由誰加載它。native 模組由 LeviLamina 自己加載;其他類型由為該類型註冊的模組管理器加載(例如腳本引擎)。
對於原生模組,LeviLamina 會:
- 把模組的文件夾加入
PATH,以便找到它放在自身旁邊的 DLL; - 加載清單的
entry所指定的 DLL。如果 Windows 因為缺少它導入的某個 DLL 或函數而無法加載,LeviLamina 會在日誌中列出缺少的內容; - 檢查該 DLL 是否使用 LeviLamina 的內存分配運算符(
ll/api/memory/MemoryOperators.h),不使用的 DLL 不會被加載; - 調用模組的
load()。
DLL 的靜態對象在 DLL 加載時、load() 之前創建:用 LL_AUTO_ 宏聲明的鉤子就是在這時安裝的(參見事件與鉤子)。
啟用
在服務端,模組在服務器線程啟動後被啟用;在客戶端,則在遊戲完成初始化時。它們按加載的順序被啟用,LeviLamina 會為每個模組輸出
“Enabling … v…”。只有當一個模組的所有 dependencies 都已啟用時,它才會被啟用。
enable() 是模組開始參與遊戲的地方:註冊它的監聽器、命令等。在遊戲運行時加載的模組(通過 /ll load)會在其 load() 之後立即被啟用。
禁用與卸載
服務器停止或客戶端窗口關閉時,LeviLamina 按與加載相反的順序禁用模組,因此一個模組會先於它所依賴的模組被禁用。
模組也可以在遊戲運行時被禁用或卸載。這時 LeviLamina 會替它清理:
- 在遊戲運行時禁用:移除該模組的事件監聽器,並禁用它的命令。
- 卸載:先禁用該模組;然後運行它的
unload(),從事件總線上移除它的監聽器和它提供的事件,並釋放它的 DLL。
當依賴某個模組的模組仍處於啟用或加載狀態時,該模組不能被禁用或卸載:LeviLamina 會回答“… still depends on …”。
loadBefore 不會建立這種關係(參見 Mod(模組系統)中的“依賴語義”)。
在運行時管理模組
LeviLamina 的 /ll 命令可以在遊戲運行時對某個模組執行這些步驟:
| 命令 | 作用 |
|---|---|
/ll load <mod> [cascade] |
加載一個位於模組根目錄但尚未加載的模組,並啟用它 |
/ll unload <mod> [cascade] |
禁用並卸載一個模組 |
/ll reload <mod> [cascade] |
卸載一個模組後重新加載它 |
/ll reactivate <mod> [cascade] |
禁用一個模組後重新啟用它 |
/ll enable <mod> [cascade] |
啟用一個已禁用的模組 |
/ll disable <mod> [cascade] |
禁用一個模組 |
/ll show <mod> [cascade] |
顯示模組的清單:名稱、作者、描述、類型、版本、入口、額外信息 |
/ll list |
列出已加載的模組 |
/ll load 要求模組的依賴已經加載。加上 cascade 時,與它相關的模組會一併處理:load 還會加載模組根目錄中依賴它的模組;
unload、reload 和 disable 會連帶依賴它的模組;enable 會先啟用它的依賴;show 會以樹的形式列出它的依賴和依賴它的模組。
在服務端,該命令為 /levilamina,簡寫 /ll,默認需要 Admin 權限等級;在客戶端為 /clilevilamina,簡寫 /clill,任何人都可以使用。
它在 LeviLamina 自己的配置文件中設置,即模組根目錄下的 LeviLamina/config/Config.json,位於
modules.command.modManageCommand(enabled,以及在服務端使用的 permission)。
相關文檔
- Mod(模組系統) —
Mod、Manifest、LL_REGISTER_MOD和模組的文件夾 - 事件與鉤子 — 模組被啟用、禁用或卸載時,監聽器和鉤子會怎樣
- 寫你的第一個 LeviLamina 模組 — 從模板一步步做出一個模組