跳到正文
本頁目錄

LegacyScriptEngine 的安裝、配置與版本

安裝

LSE 的 Node.js 引擎(legacy-script-engine-nodejs)加載失敗,報 C++ Exception: std::system_error ... [0x0000007E:system] 找不到指定的模块,依賴診斷顯示 missing module: libnode.dll(或提示缺少 node 運行庫),怎麼解決?

原因:Node.js 引擎依賴 LiteLDev 自行預編譯的 Node 運行庫(libnode.dll 及配套文件),它不是系統裡安裝的 Node.js 提供的,裝了系統 Node.js 也沒用。這個運行庫不包含在 LSE 的 GitHub release zip 裡,手動解壓安裝 LSE(或使用面板服/網上整合包)時最容易漏掉。

推薦做法:用 lip 安裝 Node.js 引擎,lip 會自動下載 libnode 等全部依賴:

shell
lip install github.com/LiteLDev/LegacyScriptEngine#nodejs

README 中也寫作 lip install LegacyScriptEngine#nodejs。不帶 #nodejs 時默認只裝 QuickJS 和 Lua 引擎,不會裝 Node.js 引擎。下載需要較好的網絡,必要時配置代理/鏡像;lip 建議更新到最新版以獲得更清晰的錯誤提示。

手動安裝(如面板服無法運行 lip):下載 https://github.com/LiteLDev/node/releases/download/v22.12.0/node-prebuilt.zip,把壓縮包裡的內容直接解壓到 mods/legacy-script-engine-nodejs/ 目錄下(文件直接放在該目錄,不要多套一層文件夾)。依賴的確切下載地址和放置位置以 LSE 包的 lip.toml(舊版本為 tooth.json)為準。也可以先在本地電腦上用 lip 裝好整個服務端再打包上傳到面板。如果之前放過舊版 libnode,先把服務端各處殘留的舊 libnode.dll 刪掉,避免加載到錯誤版本。

另外注意:各 LSE 引擎(quickjs、nodejs 等)版本必須一致;新版 LSE 不再依賴已歸檔的 LegacyParticleAPI。

適用版本:LegacyScriptEngine 當前版本(v0.23.1,LeviLamina 26.60.x)

LSE 的 Python 引擎(legacy-script-engine-python)啟動時報紅:找不到 python312.dll / python3.dll、缺少模塊或直接加載失敗,裝了 Python 3.13 也不行,該怎麼處理?

自 LSE 0.9.0 起 Python 引擎不再自帶 Python 運行環境,需要在運行服務器的機器上自行安裝對應版本的 Python:

  • LSE >=0.16.2(含當前 0.23.x)需要 Python 3.12.10;
  • 0.9.0~0.16.1 為 3.12.8;
  • <0.9.0 為 3.10.11。

版本必須匹配,裝 3.13/3.14 不行(引擎找的是 python312.dll)。安裝後確保 Python 3.12 所在目錄已加入 PATH 環境變量(多個 Python 版本可以共存,關鍵是 PATH 能找到 3.12 的 dll);也可以把 python312.dll 等放到 bedrock_server.exe 所在目錄。若直接雙擊 exe 正常、用面板啟動卻報錯,多半是面板改動了 PATH。

如果服務器上沒有 Python 插件(Python 插件極少),最簡單的做法是不安裝/卸載 Python 引擎:lip uninstall LegacyScriptEngine#python,或手動刪除 mods/legacy-script-engine-python 目錄,不影響 QuickJS/Lua/NodeJS 引擎。LSE 各引擎是獨立的 lip 包變體(#quickjs、#lua、#nodejs、#python),只裝插件實際需要的即可,裝得越多負載越大;不帶變體執行 lip install LegacyScriptEngine 只會安裝 QuickJS 和 Lua。另外若 Lua 等其他引擎同時報錯且懷疑下載損壞,可 lip cache clean 後重裝。

適用版本:LSE 0.9.0 及以上(當前 0.23.1 需 Python 3.12.10);Windows 服務端

在 LeviLamina 服務器上怎麼運行舊的 LLSE(LiteLoaderBDS 時期)JS/Lua 等腳本插件?把單個 .js 文件丟進 plugins 目錄後為什麼沒有加載?

  1. LeviLamina 本體不內置腳本引擎,只加載原生 mod。運行 LLSE 腳本插件必須先安裝 LegacyScriptEngine(LSE,它本身是 LeviLamina 的一個 mod),且版本要與當前 LeviLamina 匹配(LeviLamina 新版本剛發佈時需等待對應 LSE 版本)。推薦用 lip 安裝,會自動處理依賴:lip install LegacyScriptEngine#quickjs(JS),或 #lua、#nodejs、#python;不寫變體(lip install LegacyScriptEngine)時同時安裝 QuickJS 和 Lua 引擎。也可從 https://github.com/LiteLDev/LegacyScriptEngine/releases 手動下載成品(不要放源碼)。可用 ll list 查看已加載的 mod,確認 LSE 是否加載成功。Python 引擎需在本機安裝匹配的 Python(LSE >=0.16.2 對應 Python 3.12.10)。
  2. 安裝方法:單文件插件(.js / .lua / .py,Node.js 插件為 .llplugin 包)直接放進服務端的 plugins/ 根目錄即可;第一次啟動時 LSE 會把它遷移到 plugins/<插件名>/ 文件夾並自動生成 manifest.json,同時警告 Legacy plugins have been migrated, please restart the server to load them!,此時尚未加載,需要再重啟一次服務器(或在控制台執行 ll load <插件名>)。遷移後修改代碼請改 plugins/<插件名>/ 裡的文件。如果下載的是已帶 manifest.json 的插件文件夾,直接把整個文件夾放進 plugins/ 重啟一次即可。
  3. 若裝好引擎後個別插件仍不工作,多半是插件本身與新版本不兼容或依賴其他前置(如 GMLIB 等),請使用作者適配新版的版本;插件內部寫死的舊路徑也可能需要修改。LL2 時代的 .dll 原生插件與 LeviLamina 不兼容,無法加載。

適用版本:LeviLamina + LegacyScriptEngine 當前版本(LSE 0.23.x / LeviLamina 26.60.x)

在 LeviLamina 服務器上怎麼安裝 LegacyScriptEngine(LSE)及各語言引擎?舊命令(gitea.litebds.com/LiteLDev/legacy-script-engine-xxx、不帶變體的 lip install github.com/LiteLDev/LegacyScriptEngine 等)裝不上怎麼辦?能否手動安裝?

推薦用 lip 在服務器根目錄安裝。LSE 是一個包,每種語言引擎是它的一個變體:

shell
lip install LegacyScriptEngine#quickjs
lip install LegacyScriptEngine#lua
lip install LegacyScriptEngine#nodejs
lip install LegacyScriptEngine#python

LegacyScriptEngine 等價於 github.com/LiteLDev/LegacyScriptEngine;不帶變體時 lip 會同時安裝 QuickJS 和 Lua 兩個引擎。用哪種語言的插件就裝哪個引擎,不必全裝。

前提是服務器已用 lip 裝好 LeviLamina(lip setup 或 lip install LeviLamina):lip install 不會安裝或替換遊戲和 LeviLamina,若 LSE 需要的 LeviLamina 版本與已裝的不符會直接失敗並提示用 lip setup。其餘依賴(LegacyRemoteCall、LegacyMoney、iListenAttentively,nodejs 引擎還會裝 Node 運行時 node-prebuilt 和 7-zip-tooth)由 lip 自動安裝。舊的 gitea.litebds.com/LiteLDev/legacy-script-engine-xxx 包名已廢棄。

LSE 版本必須與 LeviLamina 版本匹配,需要舊版時用 @<版本号> 指定(變體寫在 @ 之前,如 LegacyScriptEngine#quickjs@0.23.1)。

手動安裝:到 https://github.com/LiteLDev/LegacyScriptEngine/releases 下載 LegacyScriptEngine-server-<引擎>-windows-x64.zip,把其中的 legacy-script-engine-<引擎>/ 文件夾放進服務端的 mods/ 目錄,並手動裝好 LegacyRemoteCall、LegacyMoney、iListenAttentively 等依賴(版本要匹配);nodejs 引擎還要額外解壓 node-prebuilt.zip 到同一目錄,所以 nodejs/python 更建議用 lip。需要放哪些文件、依賴哪些包可以參照該版本倉庫裡的 lip.toml(舊版本為 tooth.json)。不要用 GitHub Actions 的構建產物,容易缺組件。

LLSE 腳本插件放進 plugins/(0.23.0 起是啟動時自動創建的指向 mods/ 的鏈接)即可,啟動後會自動遷移並生成 manifest.json,重啟後加載,不用自己建文件夾。

文檔見 https://levimc.org/zh-Hant/LegacyScriptEngine/ 和教程「給服務器安裝模組」。

適用版本:LSE 0.10.0 及以上(變體式包名);當前最新 LSE 0.23.1 / LeviLamina 26.60.x / lip 0.41.x

LSE 的 quickjs、nodejs、lua、python 四個引擎都要裝嗎?怎麼判斷一個插件需要哪個引擎?

不需要全裝,用到哪種插件就裝哪個引擎(lip install LegacyScriptEngine#quickjs / #lua / #nodejs / #python;不帶變體時默認裝 quickjs 和 lua)。

判斷方法:

  1. 看插件文件後綴(.js / .lua / .py)。
  2. js 插件分 QuickJS 和 Node.js 兩種,帶 package.json 的(使用 npm 包的)一般是 Node.js 插件,否則大概率是 QuickJS。
  3. 最準確的是看插件 manifest.json 中的 type 字段(lse-quickjs、lse-nodejs、lse-lua、lse-python)以及 dependencies 裡依賴的引擎(如 legacy-script-engine-quickjs)。

裝錯或漏裝時啟動日誌也會提示缺少哪個依賴。

注意 Python 引擎需要本機安裝對應版本的 Python(LSE >=0.16.2 為 3.12.10)。

適用版本:當前所有版本(LSE 0.10.0 起為變體式包名;最新 0.23.1)

LSE 加載 Node.js 插件時自動執行 npm 安裝依賴卡住/失敗,插件因缺少 node_modules 無法加載,怎麼辦?另外為什麼插件裡 require/import 相對插件目錄,而 fs、path.resolve 卻從 BDS 根目錄開始?

LSE 的 Node.js 引擎在加載插件時,若 package.json 聲明瞭 dependencies 且插件目錄下沒有 node_modules,會自動執行 npm install --omit=dev --no-fund(使用 legacy-script-engine-nodejs 目錄下隨 lip 安裝的 node_modules/npm)。

若是 legacy-script-engine-nodejs 不是用 lip 安裝(缺少 npm)或網絡原因導致失敗:

  1. 進入出問題的插件目錄(mods/<插件名>/,即 package.json 所在目錄;新版 LSE 會在 BDS 根目錄創建指向 mods 的 plugins 鏈接),自行安裝 Node.js(https://nodejs.org/ 或 winget install OpenJS.NodeJS.LTS)後執行 npm i,網絡不好可換 npm 鏡像源或用代理。
  2. 若上次失敗留下了不完整的 node_modules,刪除後重啟即可讓 LSE 重新自動安裝。
  3. 也可以重新安裝該插件。

關於路徑:CommonJS 下 __dirname 被設置為插件目錄,模塊解析也會查找插件目錄及其 node_modules;但進程工作目錄是 BDS 根目錄,所以 fs 讀寫、path.resolve 等基於 cwd 的操作都相對 BDS 根目錄,訪問插件內文件請基於 __dirname(ESM 用 import.meta.url)拼接絕對路徑。

適用版本:LSE nodejs 引擎當前版本(0.23.x)

LSE 文檔裡說的插件目錄 /path/to/bedrock_dedicated_server/plugins 指的是哪裡?

指 BDS 服務端根目錄(與 bedrock_server_mod.exe 同一目錄)下的 plugins 文件夾。當前 LeviLamina 的模組目錄是根目錄下的 mods/,LSE 0.23.0 起會在啟動時自動創建指向 mods/ 的 plugins 鏈接(junction),所以把 LLSE 插件放進 plugins/ 或 mods/ 都可以,啟動後會被自動遷移到 mods/<插件名>/ 並生成 manifest.json,重啟後加載。

注意:若服務器根目錄下已存在一個真實的 plugins 文件夾(如舊版遺留),LSE 不會創建鏈接而是報錯 a file or directory with the same name already exists,此時應把其中插件移到 mods/ 並刪除該 plugins 文件夾。

適用版本:LSE 0.23.0 及以上(當前 0.23.x)

LeviLamina + LegacyScriptEngine 服務器的 plugins 目錄裡應該放哪些文件?下載到的 .jar、.pdb、.dll、.js/.py/.lua、壓縮包分別怎麼處理?

按文件類型處理:

  1. .jar 是 Java 版插件,不能用。
  2. .pdb 是調試符號文件,普通使用者不需要。
  3. 單獨的 .dll 不能直接裝,LeviLamina 原生模組需要作者提供的含 manifest.json 的完整文件夾/壓縮包(或用 lip 安裝)。
  4. 單文件的 .js / .lua / .py 直接放進 plugins/(LSE 0.23.0 起它是指向 mods/ 的鏈接,也可直接放 mods/),首次啟動會被自動遷移到 mods/<插件名>/ 並生成 manifest.json,重啟後才會加載(對應語言的引擎需已安裝)。
  5. 壓縮包看裡面是否有帶 manifest.json 的文件夾,有的話把該文件夾整體放進 mods/;Node.js 插件則是 .llplugin 包,直接放入即可自動解壓。
  6. LegacyMoney(原 LLMoney)是 LSE 的依賴,用 lip 安裝 LSE 時會自動安裝。
  7. 插件文件名最好去掉如 [minebbs]- 之類的前綴,因為文件名會成為模組名。

適用版本:LeviLamina 當前版本;LSE 0.23.x

LeviLamina 下如何安裝 LSE 的 Python 引擎?

在服務器根目錄用 lip 安裝 LSE 的 python 變體:lip install github.com/LiteLDev/LegacyScriptEngine#python(客戶端用 LeviLauncher 安裝)。Python 引擎還要求本機安裝對應版本的 Python(LSE >=0.16.2 需 Python 3.12.10)。Python 插件較少,非必要可不裝。

適用版本:LSE 0.16.2 及以上(當前 0.23.x)

為 LSE 寫的 Node.js 插件應該怎麼打包發佈?打包後安裝/npm install 後加載報錯怎麼辦?

有兩種方式:

  1. 官方 .llplugin 方式:把 package.json 和所有源碼打成 zip,後綴改為 .llplugin(不要把 node_modules 打進去),放進 plugins/ 目錄(plugins 是指向 mods 的鏈接);啟動時 LSE 會將其解壓到 mods/<插件名>/ 並自動執行 npm install --omit=dev,若目錄中沒有 manifest.json 會按 package.json 的入口自動生成一個,重啟後加載。
  2. 作為模組目錄/lip 包發佈:mods/<插件名>/ 下放 manifest.json(entry 指向入口 js,name 與目錄名一致,type 為 lse-nodejs,dependencies 中寫 legacy-script-engine-nodejs)以及源碼;為避免用戶連不上 npm,可把 node_modules 一併帶上,並寫 lip.toml 用 lip 安裝。

加載報錯時先檢查 manifest.json 的 entry 是否指向正確的入口文件。

適用版本:當前 LSE(0.23.x)nodejs 引擎

為了使用 SimpleTPS 這類 LSE 插件安裝 LSE 時,必須安裝 Python 版 LSE(並要求特定 C++/Python 版本)嗎?

不需要。LSE 按語言分為多個引擎變體(#quickjs、#nodejs、#lua、#python),只需安裝插件實際使用的那個,例如 JS 插件裝 lip install github.com/LiteLDev/LegacyScriptEngine#quickjs。不帶變體執行 lip install github.com/LiteLDev/LegacyScriptEngine 只會裝 QuickJS 和 Lua 引擎,不會裝 Python 引擎。只有 Python 引擎才要求本機安裝 Python(LSE >=0.16.2 為 3.12.10);用不到的 Python 版 LSE 可以 lip uninstall 掉。

適用版本:當前所有 LSE 版本(lip.toml 變體)

為什麼 legacy-script-engine-quickjs 加載不了?

常見原因是手動解壓時目錄結構錯誤:出現了嵌套文件夾(mods/legacy-script-engine-quickjs/legacy-script-engine-quickjs/...),或者目錄裡缺少 manifest.json / 是空文件夾。發佈包 zip 內自帶 legacy-script-engine-quickjs/ 頂層目錄,應保證 manifest.json 直接位於 mods/legacy-script-engine-quickjs/ 下;手動安裝還需自行裝好其依賴(LegacyRemoteCall、LegacyMoney、iListenAttentively 及匹配的 LeviLamina)。推薦直接用 lip install github.com/LiteLDev/LegacyScriptEngine#quickjs 安裝。

適用版本:LeviLamina 1.x 及以上;當前 LSE

使用 LegacyScriptEngine 的 nodejs 引擎需要單獨安裝 Node.js 嗎?

運行不需要。lip install github.com/LiteLDev/LegacyScriptEngine#nodejs 會自動下載 node-prebuilt.zip(含 libnode)放到 mods/legacy-script-engine-nodejs/,並安裝 7-zip 等依賴。只有在本機開發 Node.js 插件(npm init 等)時才需要自己裝 Node.js。

適用版本:當前 LSE nodejs 引擎

想用 JS 寫 LeviLamina 服務器插件,從零搭建環境的步驟是什麼?需要 xmake/cmake/mingw 嗎?

運行和寫 JS 插件不需要 xmake/cmake/mingw(那些只用於 C++ 模組開發)。步驟:

  1. 從 https://github.com/LiteLDev/lip/releases/latest 下載安裝 lip(lip-<version>-win-x64.msi)。
  2. 國內網絡可設置 GitHub 代理:lip config set github_proxy <代理地址>。
  3. 新建服務器目錄並 cd 進去,執行 lip install LeviLamina --accept-eula(會一併安裝匹配的 BDS)。
  4. 安裝引擎:lip install github.com/LiteLDev/LegacyScriptEngine#nodejs(或 #quickjs)。
  5. 用 lip run 或運行 bedrock_server_mod.exe 啟動。

插件放在 mods/<插件名>/(plugins/ 是指向 mods/ 的鏈接),需要 manifest.json(name 與目錄名一致,entry 為入口 js 文件,type 為 lse-nodejs 或 lse-quickjs,dependencies 中寫 legacy-script-engine-nodejs / legacy-script-engine-quickjs)和入口文件;Node.js 下 package.json 設 "type": "module" 可用 ES 模塊。API 文檔:https://levimc.org/zh-Hant/LegacyScriptEngine/。

也可手動下載,但需自行補全依賴(LegacyRemoteCall、LegacyMoney、iListenAttentively、7-zip、node-prebuilt 等)。

適用版本:lip 0.41.x;LeviLamina 26.x;LSE 0.23.x

跳過 lip、手動安裝 LSE 的 NodeJS 引擎後,加載(.llplugin)插件時提示解碼/解壓失敗,怎麼辦?

缺少 7za.exe。LSE nodejs 引擎調用 7za.exe 解壓 .llplugin,lip 安裝 #nodejs 變體時會通過依賴 github.com/LiteLDev/7-zip-tooth 自動把 7za.exe 放到服務端根目錄;手動安裝時需自行從該倉庫獲取 7za.exe 放到服務端根目錄(不需要運行它)。另外 libnode 應位於 mods/legacy-script-engine-nodejs/(來自 node-prebuilt.zip),不是服務端根目錄。推薦直接用 lip install github.com/LiteLDev/LegacyScriptEngine#nodejs 安裝。

適用版本:當前 LSE nodejs 引擎(手動安裝時)

LeviLamina 下安裝 iLand 等 Lua 插件後完全不加載、控制台也沒有任何報錯,怎麼解決?

通常是沒裝對應語言的腳本引擎或插件依賴的庫,或者插件文件不完整。在服務器根目錄用 lip 安裝 Lua 引擎:lip install LegacyScriptEngine#lua(不帶變體的 lip install LegacyScriptEngine 會同時安裝 QuickJS 和 Lua 引擎),lip 會自動處理依賴。啟動日誌中應能看到 Lua 引擎被加載。若插件安裝不完整,可先 lip cache clean 清理緩存再重新安裝插件。

適用版本:LSE 0.23.x / lip 0.41.x(當前版本)

在較舊 BDS(如 1.21.70)的 LeviLamina 服務端上用 lip 安裝 LSE nodejs 引擎報依賴衝突,怎麼安裝對應版本?

不帶版本號時 lip 默認安裝最新 LSE,其依賴的 LeviLamina 版本與舊服務端衝突。需指定與服務端匹配的 LSE 版本,語法為 <repo>#<variant>@<version>(變體寫在 @ 之前),例如 lip install github.com/LiteLDev/LegacyScriptEngine#quickjs@0.11.3(BDS 1.21.70 / LeviLamina 1.2.x 時期)。可查看 LSE CHANGELOG 中各版本支持的 LeviLamina 版本來選擇。

LSE 0.10.0 起變體用 #nodejs 寫法,舊文檔裡的 legacy-script-engine-nodejs 包名是 0.10.0 以前的。

注意:LSE 0.13.x 及更早版本 tooth.json 中 nodejs 變體用了 uncompressed 類型資源下載 node,當前 lip(v0.38 起讀取 tooth.json 時不支持 uncompressed)會認為該版本沒有 nodejs 變體而無法安裝;這類舊版本的 nodejs 引擎需改用 lip v0.37.0 及更早版本安裝,或從對應 GitHub Release 手動下載 legacy-script-engine-nodejs 包並把 node-prebuilt.zip 解壓到其目錄。LSE 0.14.0 起 nodejs 變體改用 zip 資源,可由當前 lip 正常安裝。

適用版本:LSE 0.10.0 及以上;當前 lip 0.41.x

LSE 的 Python 引擎和 NodeJS 引擎安裝時有什麼需要注意的?

現在各引擎都是 LegacyScriptEngine 包的變體,用 lip 安裝即可:lip install github.com/LiteLDev/LegacyScriptEngine#nodejs / #python(#quickjs、#lua 同理),lip 會自動處理依賴(NodeJS 變體會一併下載 node 預編譯運行時到 legacy-script-engine-nodejs 目錄)。

Python 引擎需要在運行它的機器上安裝對應版本的 Python:LSE >=0.16.2 用 3.12.10,>=0.9.0 <0.16.2 用 3.12.8,<0.9.0 用 3.10.11;引擎會從 PATH 中名字含 Python 的目錄查找 Lib/DLLs/site-packages,所以安裝時需把該 Python 加入 PATH。

適用版本:LSE 0.23.x(Python 版本對應表適用於所有版本)

配置

LeviLamina 下 LSE 腳本插件的 manifest.json 放在哪裡、怎麼寫(type 填什麼)?提示未知類型 / 插件不被識別怎麼辦?舊插件自帶的自定義 manifest.json 衝突怎麼辦?如何用 ll load 手動加載?

每個 mod/插件都必須在 plugins/<插件文件夹>/manifest.json(服務端模組根目錄為 plugins/)放一個符合 LeviLamina 規範的清單,至少包含 name(與文件夾名相同)、entry(入口文件)、type;可用 dependencies / optionalDependencies / loadBefore 控制依賴與加載順序。

type 取值:

  • C++ 原生 mod 填 native
  • QuickJS 插件填 lse-quickjs
  • Lua 填 lse-lua
  • Node.js 填 lse-nodejs
  • Python 填 lse-python(entry 為 __init__.py)

同時必須安裝對應的 LSE 引擎(如 lip install LegacyScriptEngine#quickjs),否則該 type 無人處理、插件不會被識別。

清單不能使用自定義格式,若舊插件自己也用了名為 manifest.json 的文件,需要把它改名或改成兼容格式。偷懶的做法是直接把單個 .js 等文件丟進 plugins 根目錄啟動一次,LSE 會自動遷移並生成清單,按提示重啟即可。

手動加載用控制台命令 ll load <插件文件夹名>。

清單格式文檔:https://levimc.org/zh-Hant/LeviLamina/api_reference/mod/

適用版本:LeviLamina 1.x 及以上,對應 LSE(含 LeviLamina 26.60.x / LSE 0.23.x)

LSE 中 data.name2xuid 等玩家信息查詢接口返回空/沒有返回值(尤其對之前進過服的玩家),是接口壞了嗎?

不是接口壞了。這些接口(data.name2xuid、data.xuid2name、data.name2uuid、data.getAllPlayerInfo、data.fromName 等)依賴 LeviLamina 的 PlayerInfo 服務。該服務默認不隨服務器啟動,只有在有插件調用時才啟用,因此之前進過服的玩家不會被記錄,查詢返回空。

解決:在 LeviLamina 配置文件(mods/LeviLamina/config/Config.json)的 targeted.playerInfo 中把 alwaysLaunch 設為 true,重啟服務器;之後進服的玩家會被記錄。

適用版本:LeviLamina 服務端(當前 26.60.x 仍適用);LSE

LSE 的 Node.js 插件 manifest.json 裡 entry 寫成了絕對路徑(如指向 E 盤),換到別的服務器就無法加載,正確寫法是什麼?

entry 應寫相對於插件(模組)目錄的路徑(通常就是入口腳本文件名),不要用絕對路徑:LSE 加載時用 模组目录 / entry 拼出入口路徑,絕對路徑會原樣生效,換機器就找不到文件。

示例:

json
{
  "entry": "LLSE-FakePlayer.js",
  "name": "LLSE-FakePlayer",
  "type": "lse-nodejs",
  "dependencies": [ { "name": "legacy-script-engine-nodejs" } ]
}

注意:Node.js 插件包(.llplugin)由 LSE 自動遷移時,生成的 manifest.json 的 entry 是按 package.json 的 main 解析出的規範化絕對路徑(或解析失敗時為空),這正是 entry 變成本機絕對路徑的常見來源;遷移後請檢查並手動改成相對路徑。

適用版本:LeviLamina 1.x 及以上;LSE 0.23.x(當前版本)

LSE 的各個引擎(quickjs、nodejs、lua、python)版本不一致會有問題嗎?

會,LSE 各引擎的版本需要保持一致。現在各引擎是同一個 LegacyScriptEngine 包的變體(#quickjs、#lua、#nodejs、#python),用 lip 安裝/升級時版本會保持一致,且共同依賴同一版本範圍的 LeviLamina、LegacyRemoteCall、LegacyMoney、iListenAttentively。

LeviLamina 下 LSE 插件(如依賴 nodejs 引擎或 LegacyRemoteCall/GMLIB 的插件)不被識別/不加載,報“無法識別的模組類型:lse-nodejs”,怎麼辦?

該報錯表示加載這個插件時對應的引擎(legacy-script-engine-nodejs)尚未加載或未安裝。LeviLamina 按 manifest.json 中的依賴關係排序加載,插件目錄下的 manifest.json 要寫明 dependencies,例如依賴 legacy-script-engine-nodejs 或 LegacyRemoteCall 的插件必須聲明依賴;不寫依賴時只能靠默認順序(按名稱排序)碰運氣。manifest.json 還支持 optionalDependencies、conflicts、loadBefore 等字段。

同時確認已用 lip 安裝對應引擎變體。

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

在 LeviLamina 上用 LSE 插件時,還需要另外裝 LL2 的 PAPI(PlaceholderAPI)嗎?

不需要,LL2 的 PAPI 無法在 LeviLamina 上使用。第三方庫 GMLIB 自帶 PAPI 功能,依賴 PAPI 的插件安裝 GMLIB 即可。

適用版本:LeviLamina;第三方 GMLIB。未能從源碼或文檔中直接證實,僅供參考。

在 LeviLamina + LSE 服務器上裝了 OneTitle 稱號插件,插件已加載,但玩家聊天消息裡沒有顯示稱號,怎麼辦?

OneTitle 本身只導出 API/PAPI,不負責修改聊天格式,需要搭配聊天格式插件使用。例如 ChatFormatter(需配合 GMLIB),在其配置的聊天格式中加入 OneTitle 提供的 PAPI 佔位符(如 %onetitle%)即可。

適用版本:第三方插件 OneTitle / ChatFormatter / GMLIB。未能從源碼或文檔中直接證實,僅供參考。

用不到 Lua/Python 引擎和 LegacyMoney(原 LLMoney),能否禁用這些組件以加快啟動和節省資源?

不需要的腳本引擎可以去掉:LSE 的每個引擎都是獨立的 mod 目錄(mods/legacy-script-engine-quickjs、mods/legacy-script-engine-lua、mods/legacy-script-engine-python、mods/legacy-script-engine-nodejs),刪掉不用的那個目錄即可。

用 lip 時,單獨安裝的變體可用 lip uninstall 卸載(如 lip uninstall LegacyScriptEngine#python);但默認安裝(lip install LegacyScriptEngine 不帶變體)會同時裝 QuickJS 和 Lua,二者是默認變體的依賴,lip 不會單獨卸載仍被需要的依賴。想只保留一個引擎,應卸載 LegacyScriptEngine 後改裝單個變體(如 lip install LegacyScriptEngine#quickjs)。

但 LegacyMoney 不能刪:當前版本中 LegacyMoney 是 LSE 的必需依賴(manifest.json 的 dependencies 中列出 LegacyMoney、LegacyRemoteCall、iListenAttentively),刪掉後 LeviLamina 會以缺少依賴(MissingDependency)為由拒絕加載所有 LSE 引擎。

適用版本:LegacyScriptEngine 0.23.x(LeviLamina 26.60.x)及當前版本

裝了 BehaviorLog(行為日誌)LSE 插件後,後臺一直刷命令方塊執行的日誌,怎麼關掉?

打開 BehaviorLog 的配置文件 ./plugins/BehaviorLog/config.json,找到 onCmdBlockExecute 項,把裡面的 true 改成 false(數值項 1 改成 0),保存後重啟服務器(或重載插件)。插件說明見 https://www.minebbs.com/threads/behaviorlog.7759/

適用版本:第三方 LSE 插件 BehaviorLog,具體配置路徑和鍵名以所用插件版本為準。未能從源碼或文檔中直接證實,僅供參考。

版本與兼容性

舊版 LeviLamina 上裝最新版 LSE 裝不上或提示依賴缺失(如提示需要更新的 LeviLamina),LSE 和 LeviLamina 的版本怎麼對應?怎麼裝舊版 LSE?

LSE 的版本號與 LeviLamina 不一一相同,但每個 LSE 版本只兼容特定範圍的 LeviLamina,新版 LSE 不能用在舊版 LL 上(例如當前 LSE 0.23.x 要求 LeviLamina 26.60.*)。

查對應關係:看 LSE 對應 release tag 提交裡的 lip.toml(0.23.1 及更早為 tooth.json)中依賴的 github.com/LiteLDev/LeviLamina 版本範圍,或看 CHANGELOG 中“Adapted to LeviLamina xx”的記錄。

舊 LL 需用 lip 指定匹配的舊版本 LSE,變體寫在 @ 之前,例如 lip install LegacyScriptEngine#quickjs@0.13.2;lip 會按該版本聲明的依賴安裝配套的 LegacyRemoteCall、LegacyMoney 等。也可以從各項目 GitHub Releases 下載對應舊版本手動安裝。GMLIB 等第三方 native 前置同樣必須使用與當前 LeviLamina/BDS 版本對應的版本。

歷史例子:LeviLamina 0.13.x(BDS 1.21.2/1.21.3)對應 LSE 0.8.20(當時包名為 gitea.litebds.com/LiteLDev/legacy-script-engine-*)。

適用版本:當前版本(LSE 0.10.0 及以上可用 LegacyScriptEngine#<变体>@<版本> 安裝,更早版本使用舊 gitea 包名)

BDS 26.20(LeviLamina 26.20.x)上裝了最新版 LSE 後不工作、LSE 插件不加載,該裝哪個版本的 LSE?

LSE 每個版本只對應一個 LeviLamina 小版本系列,不能跨版本使用。最新的 LSE 0.23.x 面向 LeviLamina 26.60.*(BDS 26.60),不能在 26.20 上運行。LeviLamina 26.20.x 對應 LSE 0.19.x,應安裝該系列最後一個版本 LSE 0.19.7。

版本對應關係:

  • 0.19.x → LL 26.20.*
  • 0.20.0 → LL 26.32.*
  • 0.21.x → LL 26.40.*
  • 0.22.x → LL 26.51.*
  • 0.23.x → LL 26.60.*

查看 LSE 的 CHANGELOG 中 “Adapted to LeviLamina xx” 的條目即可確認某版本適配哪個 LL。

適用版本:LeviLamina 26.20.x;LSE 0.19.x~0.23.x(版本對應原則適用於當前版本)

LeviLamina 更新到新 BDS 版本後,LSE 報一堆 fatal 錯誤或提示 mod 版本太舊,JS 插件都跑不起來,怎麼辦?

這是 LSE 還沒有適配新版 LeviLamina,舊版 LSE 無法加載。可以等 LSE 發佈正式適配版本再一起升級,或者先把 LeviLamina 保持在與當前 LSE 匹配的版本。

著急的話,可以登錄 GitHub 後到 https://github.com/LiteLDev/LegacyScriptEngine/actions 下載最新的構建產物(artifact)臨時使用。依賴 GMLIB 等第三方前置庫的插件,還要等這些前置庫也完成適配。

適用版本:當前版本(每次 LeviLamina 跟進新版 BDS 時都會出現)

更新 GMLIB 後,LSE 插件通過 GMLIB-LegacyRemoteCallApi 調用 GMLIB 接口(如 GMLIB_API::getServerAverageTps)時報接口不存在/報錯,之前版本正常,是什麼原因?

新版 GMLIB-LegacyRemoteCallApi(LRCA)在清單中被設為 passive:沒有任何插件在 manifest 中依賴它時不會被加載(可用 ll show GMLIB-LegacyRemoteCallApi 確認)。

解決:在調用方插件的 manifest.json 中把 GMLIB-LegacyRemoteCallApi 寫進 dependencies(必選依賴),或寫進 optionalDependencies(可選依賴,沒裝也能正常加載)。如果代碼是被宿主插件引用的子模塊,沒有自己的 manifest,就要把依賴加到宿主插件上。

運行時可用 ll.getAllPluginInfo().some(p => p.name === "GMLIB-LegacyRemoteCallApi") 判斷是否已加載,未加載時提示用戶安裝 GMLIB 和 LRCA;部分接口在低版本 LRCA 中不存在,必要時還要檢測版本。

若報錯來自 GMLIB 本身(如 bad optional_ref access),屬於 GMLIB 的 bug,應更新到 GMLIB 已修復的版本或向其作者反饋,而非 LSE 問題。

適用版本:LeviLamina 1.x 及以上;GMLIB / GMLIB-LegacyRemoteCallApi(第三方)。未能從源碼或文檔中直接證實,僅供參考。

LSE 插件用 BinaryStream 自己發包刷新告示牌,更新服務器版本後失效了,怎麼改?

新協議中方塊座標的 y 寫法變了:協議版本 >= 944 時 y 座標要用 writeVarInt(有符號),舊版本用 writeUnsignedVarInt。

示例:

js
bs[mc.getServerProtocolVersion() >= 944 ? "writeVarInt" : "writeUnsignedVarInt"](pos.y);

適用版本:BDS 協議版本 944 及以上(LSE 0.18.4 起觀察到)。未能從源碼或文檔中直接證實,僅供參考。

LegacyScriptEngine 的 NodeJS 引擎(legacy-script-engine-nodejs)內置的是哪個版本的 Node.js?

Node.js v22.12.0。LSE 通過 lip 安裝 nodejs 變體時,會一併下載 LiteLDev/node 的 v22.12.0 預編譯包(node-prebuilt.zip),ScriptX 的 V8 後端也是基於 node v22.12.0 構建的。

適用版本:LSE 0.9.0 及以上(當前 v0.23.1)

LSE nodejs 引擎加載失敗,報 Raw Seh Exception: [0xC0000005:ntstatus] 訪問違例(如 legacy-script-engine-nodejs 加載失敗),怎麼解決?

LSE 各個引擎(quickjs、lua、nodejs、python)的版本必須一致,否則必然崩潰,例如 0.18.0 的 lua 配 0.18.2 的 nodejs 就會出錯。把所有已安裝的引擎更新/重裝到同一版本即可,例如 lip install LegacyScriptEngine#nodejs(與已安裝的 #quickjs、#lua 保持同一版本);不需要 nodejs 插件也可以直接卸載 nodejs 引擎。

同時 LeviLamina 也要更新到該 LSE 版本要求的版本(如 LSE 0.23.x 要求 LeviLamina 26.60.*)。

適用版本:當前版本(LSE 0.23.x 對應 LeviLamina 26.60.*)

LSE 中獲取玩家延遲的 API(player.getDevice().avgPing / lastPing)在 26.20 正常,在 26.51 上獲取不到,是什麼原因?

可能是服務端使用 NetherNet 協議導致拿不到相關網絡統計信息,可嘗試把服務端切換為 RakNet 再試。

適用版本:BDS 26.51 及以上(推測性答案)。未能從源碼或文檔中直接證實,僅供參考。

LSE 的 Python 引擎還推薦使用嗎?LSE 的 JS/Lua 引擎會停止維護嗎?

JS(QuickJS、Node.js)和 Lua 引擎會繼續維護。

Python 引擎目前仍作為 LegacyScriptEngine#python 變體提供(lip install LegacyScriptEngine#python),但需要先在機器上安裝 Python(LSE >=0.16.2 需要 Python 3.12.10),且有 threading/asyncio 不可用等已知問題;維護者建議需要 Python 插件生態的用戶改用 LeviStone(在 LeviLamina 上運行 Endstone 的 Python 插件)。

適用版本:當前版本(LSE 0.23.x)

升級到新版 LeviLamina(如 26.10)後 LSE 加載報錯,LSE 正式版還沒適配新版本,怎麼提前用上?

LSE 正式版發佈前,可去 GitHub Actions(https://github.com/LiteLDev/LegacyScriptEngine/actions)中 build.yml 工作流的一次成功(綠色)運行裡下載構建產物(需登錄 GitHub)。產物按 <仓库>-<commit>-<server|client>-<引擎>-windows-x64 命名,服務端請選 server 且對應引擎(nodejs/quickjs/lua/python)的包。

NodeJS 引擎還需要 node 運行時(https://github.com/LiteLDev/node/releases/download/v22.12.0/node-prebuilt.zip,解壓到 mods/legacy-script-engine-nodejs/),正式版 nodejs 變體另外依賴 7-zip-tooth。

依賴的 LegacyMoney、LegacyRemoteCall、iListenAttentively 可用 lip 安裝(lip install github.com/LiteLDev/LegacyMoney 等);但它們的正式版同樣鎖定某個 LeviLamina 小版本(目前為 26.60.*),若 lip 報與新版 LeviLamina 衝突,也需要到各自倉庫的 Actions 下載適配新版的構建。

適用版本:當前版本(LSE 正式版尚未適配最新 LeviLamina 的過渡期)

把服務器從 BDS 1.21.93 升級到 1.21.124 後,LSE 加載時報一堆紅字、BackupHelper 等插件無法正常工作,報錯涉及 LegacyParticleAPI,怎麼解決?

先確認插件已更新到適配新版本的版本(例如 BackupHelper 0.9.1 不兼容,需更新到 0.14.0)。LegacyParticleAPI 是舊版 LSE 的依賴,LSE 0.15.0 起已移除,直接卸載/刪除 LegacyParticleAPI 即可。

加載地圖時的紅字若是低版本存檔升級導致,一般不影響使用。

適用版本:LSE 0.15.0 及以上(從更舊版本升級時)

老 LXL(LiteXLoader/LLSE)插件開發者回坑:現在還用 LXL 嗎?支持多維度嗎?舊插件寫法還能用嗎?

LXL/LiteLoaderBDS 已不再使用,現在的方案是 LeviLamina + LegacyScriptEngine(LSE,LLSE 腳本引擎的延續)。

LSE 沿用同一套 LLSE API,舊的 LLSE 插件幾乎無需修改即可運行(部分插件可能因事件觸發時機差異等原因無法正常工作):把舊插件放進 plugins/ 啟動服務器,LSE 會自動遷移並生成 manifest.json,重啟後加載。

多維度方面,LeviLamina 生態中有 MoreDimensions 庫(lip install github.com/LiteLDev/MoreDimensions)提供自定義維度 API,它本身不添加維度,需要配合使用其 API 的模組。

適用版本:LeviLamina 26.60.x;LSE 0.23.x(當前版本)