跳到正文
本頁目錄

模組生命週期

本頁說明 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 在加載任何模組之前,先根據清單制定一個計劃:

  1. 加載哪些模組。 從每個不是 passive 的模組出發,加上它們需要的模組:它們的 dependencies,以及已安裝且版本匹配的 optionalDependencies。passive 模組只在某個會被加載的模組依賴它時才會被加載。
  2. 其中哪些不能運行。 以下情況的模組會被排除:缺少某個依賴,或依賴的版本不在它要求的範圍內;它的 platform 不是當前平臺 (server 或 client;universal 或未寫 platform 則兩端都可運行);它在 conflicts 中列出了計劃中的另一個版本匹配的模組; 它的某個依賴被排除;或者它處於依賴環中。日誌會寫明原因,例如“… will not be loaded because it conflicts with …”。
  3. 按什麼順序。 依賴和可選依賴排在使用它們的模組之前;聲明瞭 loadBefore 的模組排在它列出的模組之前。 相互之間沒有順序要求的模組按名稱排序。

然後按這個順序逐個加載模組。依賴加載失敗的模組也會被跳過。

加載

在服務端,LeviLamina 在遊戲的 main 開始時、遊戲本身運行之前加載模組;在客戶端,則是在 PreLoader 把 LeviLamina 加載進遊戲時。此時遊戲、它的世界和玩家都還不存在。

模組的 type 決定由誰加載它。native 模組由 LeviLamina 自己加載;其他類型由為該類型註冊的模組管理器加載(例如腳本引擎)。 對於原生模組,LeviLamina 會:

  1. 把模組的文件夾加入 PATH,以便找到它放在自身旁邊的 DLL;
  2. 加載清單的 entry 所指定的 DLL。如果 Windows 因為缺少它導入的某個 DLL 或函數而無法加載,LeviLamina 會在日誌中列出缺少的內容;
  3. 檢查該 DLL 是否使用 LeviLamina 的內存分配運算符(ll/api/memory/MemoryOperators.h),不使用的 DLL 不會被加載;
  4. 調用模組的 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)。

相關文檔