跳到正文
本頁目錄

插件與引擎

本頁說明腳本插件對 LeviLamina 和 LSE 來說是什麼:它放在哪裡,它的清單如何選定運行它的引擎,加載和卸載時會發生什麼, 以及為 LLSE 編寫的插件如何變成 LeviLamina 插件。

插件就是模組

LeviLamina 從服務器的 mods 文件夾加載模組。每個模組都是一個帶有 manifest.json 的文件夾。C++ 模組的類型為 native;腳本插件的類型是運行它的引擎的類型:

manifest.json 中的 type 引擎 引擎模組
lse-quickjs JavaScript(QuickJS) legacy-script-engine-quickjs
lse-lua Lua legacy-script-engine-lua
lse-nodejs JavaScript(Node.js) legacy-script-engine-nodejs
lse-python Python legacy-script-engine-python

每個引擎本身都是一個 LeviLamina 模組,由 LegacyScriptEngine 包的一個變體安裝(#quickjs、#lua、#nodejs、 #python;見語言支持)。引擎加載時會向 LeviLamina 註冊為其插件類型的管理器, LeviLamina 會把該類型的每個模組交給它。

一個最小的 QuickJS 插件:

Text Only
mods/
    MyPlugin/
        manifest.json
        main.js
JSON
{
    "entry": "main.js",
    "name": "MyPlugin",
    "type": "lse-quickjs",
    "dependencies": [
        {
            "name": "legacy-script-engine-quickjs"
        }
    ]
}
  • entry 是引擎要運行的腳本,相對於插件的文件夾。
  • name 是插件的名稱,請與文件夾名保持一致。
  • type 指定由哪個引擎運行它。
  • dependencies 列出必須先加載的模組。在這裡寫上引擎,它就會在插件之前加載。依賴其他插件的插件也要寫上那個插件: 被依賴的插件先加載,因此它的事件監聽器也先註冊、先被調用。

寫你的第一個腳本插件一步步搭建了這個結構。 Node.js 插件還有一個 package.json,Python 插件還有一個 pyproject.toml;見語言支持。

plugins 與 mods

每個引擎加載時,都會把服務器文件夾中的 plugins 做成指向 mods 的鏈接(在 Windows 上是目錄聯接),因此 plugins/MyPlugin 和 mods/MyPlugin 是同一個文件夾。如果 plugins 已經存在且與 mods 不是同一個文件夾,LSE 會記錄一條錯誤,並保持它不變。

每個插件一個引擎實例

每個插件都運行在自己的腳本引擎實例中,實例以插件命名。LSE 加載插件時會:

  1. 對 Node.js,如果插件的 package.json 有依賴且還沒有 node_modules 文件夾,就在插件文件夾中運行 npm install --omit=dev;對 Python,如果插件的 site-packages 文件夾還不存在且插件列出了依賴,就運行 pip install 把依賴安裝到其中;
  2. 創建一個新的引擎實例,以及一個以插件命名的日誌記錄器;
  3. 綁定 API(mc、ll、log 等,見 API 的工作方式);
  4. 運行引擎的基礎庫(QuickJS、Lua 和 Python);
  5. 運行入口腳本。

由於每個插件都有自己的實例,插件之間不共享全局變量。要調用另一個插件的函數,用 ll.exports 導出、用 ll.imports 導入(見 ll API)。

如果入口腳本拋出錯誤,插件就不會被加載:控制台會顯示錯誤及其調用棧,腳本在出錯之前註冊的事件監聽器、定時任務和導出函數都會被移除。

在服務器運行時加載

插件可以在服務器啟動之後加載,例如用 LeviLamina 的 ll reload <插件名>。此時會立即調用它的 onServerStarted 監聽器,併為每個在線玩家各調用一次 onPreJoin 和 onJoin 監聽器,因此在這些事件中做初始化的插件和啟動時加載的效果一樣。

卸載

在服務器運行時卸載插件,會先為每個在線玩家調用它的 onLeft 監聽器,再調用用 ll.onUnload 註冊的函數。然後 LSE 移除插件的定時任務、事件監聽器和導出函數,並釋放它的引擎實例。插件用 mc.newCommand 註冊的命令會留在遊戲中, 但沒有了回調,直到服務器重啟。

在客戶端上

在 Windows 上的 Minecraft 客戶端中,插件的腳本只在本地世界運行時運行(單人世界相當於一個本地服務器):在它的服務器啟動後開始, 在它停止時停止。加入別人的服務器時,腳本不會運行。

為 LLSE 編寫的插件

LLSE 插件是直接放進 plugins/ 的單個文件。引擎加載時,會在 mods/(因而也在 plugins/)中查找這樣的文件:

引擎 遷移的文件
QuickJS *.js
Lua *.lua
Python *.py
Node.js *.llplugin(zip 壓縮包)

對每個文件,引擎會創建文件夾 mods/<不带扩展名的文件名>/,把文件移進去(Node.js:把壓縮包解壓進去並刪除壓縮包), 如果那裡還沒有 manifest.json 就寫入一個:文件是入口(Node.js:壓縮包中找到的入口腳本),文件名是插件名,引擎是它的類型和依賴。然後它會記錄插件已遷移、 需要重啟才能加載:再重啟一次服務器即可運行它們。

如果文件夾中已有同名文件,遷移會報錯失敗。要關閉遷移,在引擎的配置中把 migratePlugins 設為 false。

引擎的配置

每個引擎都讀取自己模組文件夾中的 config/config.json(例如 mods/legacy-script-engine-quickjs/config/config.json), 文件不存在時會用默認值寫入:

鍵 默認值 含義
version 3 文件格式的版本。
migratePlugins true 啟動時遷移 LLSE 插件(見上文)。
debugCommandLevel 遊戲管理員(OP) 誰可以運行引擎的調試命令(jsdebug、luadebug)。
fixLegacyAddons 未設置 僅 Node.js:修復用低於 11.1.0 的 node-gyp 構建的原生插件(addon)。