跳到正文
本頁目錄

LegacyScriptEngine:綜合問題

這個項目的目的是什麼?

該項目的目的是在 LeviLamina 上運行 LLSE 插件。

這個項目支持所有 LLSE 插件嗎?

幾乎支持所有 LLSE 插件,但由於事件觸發時機的差異等原因,部分插件可能無法正常工作。

這個項目會維持多久?

只要我們維護者有能力、有時間維護這個項目就會一直維護下去。

LSE 的 Node.js 插件支持熱重載嗎?用 ll reload 後提示成功,隨後又輸出 NodeJs plugin XXX exited,是重載失敗了嗎?

支持。早期版本(2024 年)Node.js 引擎不支持重載、執行會出錯,但 LSE 0.9.0 起已修復插件重載(含 nodejs/qjs/lua),卸載時會停止該插件的 Node.js 環境。用法:控制台執行 ll reload <插件名>,也可以 ll unload <插件名> 後再 ll load <插件名>。

重載成功提示之後又出現 [legacy-script-engine-nodejs] NodeJs plugin XXX exited with code 0. 並不是失敗:實際順序是先退出舊實例再重載成功,但“重載成功”是命令輸出、立即顯示,而 exited 是通過 logger 異步打印、有延遲,所以看起來順序顛倒。當前版本中退出碼為 0 時該消息以 Debug 級別輸出,默認日誌級別下通常看不到;若以 Error 級別出現且退出碼非 0,則說明插件是異常退出,需要查看前面的報錯。

注意:LSE 架構源自 LL 早期,重載並非百分之百可靠。用 mc.newCommand 註冊了命令的插件重載後,舊命令仍留在遊戲中,回調會被移除(執行時會提示 is the plugin unloaded?);若重載後出現異常,直接重啟服務器,並保持 LeviLamina 與 LSE 為最新版本。

適用版本:LegacyScriptEngine 0.9.0 及以上(Node.js 引擎);LeviLamina 1.x 及以上

LSE 的 JS 插件(QuickJS / Node.js 引擎)能用 ES Module 的 import/export 語法嗎?用 import { xxx } from "./xxx" 加載時報 Failed to load plugin ...: Unexpected token '{' 是怎麼回事?

兩種引擎現在都支持 ESM:

  1. QuickJS 引擎:原生支持 ES Module(ES2020)。但 ScriptX 使用 quickjs-libc 的 module loader,加載 manifest.json 指定的入口模塊時,會把 base path 設為當前工作目錄(即 BDS 服務端程序所在目錄),而不是插件目錄,所以入口文件裡的相對路徑 import(如 import { initCommand } from "./command/command.js")會解析失敗,報 Failed to load plugin xxx: Unexpected token '{'。解決辦法:入口文件中改用相對工作目錄的路徑,例如 import { initCommand } from "./plugins/your_plugin/command/command.js";或讓入口文件只 import 真正的入口模塊,之後其它模塊之間的 import 都按標準 ESM 規則解析。也可以用 esbuild 等打包成單個 js 文件。
  2. Node.js 引擎:自 LSE 0.10.6 起(PR #268)支持 ESM,在插件的 package.json 中設置 "type": "module" 即按 ES 模塊加載(不設置默認為 CommonJS)。注意 ESM 中 import 的文件需帶後綴名,靜態 import 語句只能寫在模塊頂層(不能放在 try 塊等裡面)。
  3. 不支持直接加載 TypeScript,需先用 tsc 等編譯成 JS(目標模塊格式選 ESM 或 CommonJS 均可)。

詳見文檔 https://lse.levimc.org/zh/apis/LanguageSupport/ 的“關於 QuickJS ESModule 的路徑解析行為”一節。

適用版本:QuickJS ESM:LSE 各版本;Node.js ESM:LSE 0.10.6 及以上

LegacyScriptEngine(LSE)和 LeviLamina(LL)是什麼關係?LXL/LLSE/LSE 等縮寫分別是什麼?

LeviLamina(LL)是 mod 加載器本體,只直接加載原生(native,C++ 編寫的 .dll)mod;LegacyScriptEngine(LSE)本身是一個 LeviLamina 原生 mod,為腳本插件提供 LLSE API 運行環境,腳本插件依賴它運行。LSE 按語言分為四個引擎:QuickJS(JS,支持 ES Module)、Lua、Node.js(支持 npm)、Python(CPython,支持 pip),服務器上用 lip 安裝對應變體,如 lip install LegacyScriptEngine#quickjs(#lua/#nodejs/#python),客戶端用 LeviLauncher。腳本插件 manifest.json 中的 type 為 lse-quickjs、lse-lua、lse-nodejs、lse-python,原生 mod 為 native。

演進關係:LL1 時代的腳本引擎叫 LXL(LiteXLoader)→ LL2(LiteLoaderBDS,LLBDS)時代叫 LLSE → LL3(LeviLamina)上的 LSE,均由 LiteLDev/LeviMC 維護;LSE 能運行絕大多數舊 LLSE 插件,但不是 100% 兼容。其他常見縮寫:LO = LeviOptimize(性能優化),LAC = LeviAntiCheat(反作弊)。文檔:https://levimc.org/LegacyScriptEngine/(舊地址 lse.levimc.org、docs.levimc.org/LegacyScriptEngine/ 已被該地址取代)。

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

LSE 中多個插件監聽同一個事件(如 onChat、onLeft),其中一個插件 return false 攔截後,其他插件還能收到事件嗎?執行順序是怎樣的?LSE 有事件優先級嗎?

能收到。當前 LSE 會依次調用該事件的所有監聽器,順序就是註冊順序(一般等於插件的加載順序)。某個監聽器返回 false 只會把這個事件標記為攔截,讓 BDS(LeviLamina 事件)不再處理它,例如被攔截的聊天消息所有人都看不到,但不會阻止其他 LSE 插件的監聽器繼續收到這個事件。

LSE 的 mc.listen 沒有優先級參數。如果需要控制先後,可以在插件 manifest.json 裡用 dependencies 聲明依賴:被依賴的插件先加載,它的監聽器也就先註冊、先執行。如果需要真正的事件優先級(例如做禁言插件,要在其他插件之前攔截 TextPacket 或聊天事件),請改用 C++ mod,在 LeviLamina 的 EventBus 上以更高的 EventPriority 註冊監聽。該行為為 0.4.12 之後的事件分發行為。

適用版本:LSE 當前版本

LSE(LegacyScriptEngine)腳本插件能否給玩家打開一個類似箱子的容器界面(假箱/虛擬容器/箱子菜單),並處理玩家點擊?

LSE 沒有直接打開容器界面或箱子菜單的 API,也已徹底沒有舊 LLSE 的 NativeAPI(無法 hook)。

  1. 僅展示(只讀查看):可以純 LSE 發包實現。用 BinaryStream 寫入數據後 createPacket,再用 packet.sendTo(player) 或 pl.sendPacket(packet) 只發給目標玩家,依次發送:UpdateBlockPacket(在玩家附近如頭頂偽造一個箱子方塊,服務器裡實際不存在,其他玩家看不到)→ BlockActorDataPacket(寫方塊實體 NBT,Items 列表裡每個物品要帶 Slot)→ ContainerOpenPacket 打開容器。打開容器必須對應一個容器方塊,不能憑空打開;查看結束後再發包恢復原方塊。這只是客戶端顯示,玩家不能真正拿取物品。經驗:箱子可用、漏斗不行;玩家正打開聊天界面時客戶端不會彈出容器,可讓玩家通過輸入命令觸發。協議參考 Mojang 官方 https://github.com/Mojang/bedrock-protocol-docs(wiki.vg 的 Bedrock 協議頁已過時)。
  2. 可交互的箱子菜單(點擊物品執行操作):純 LSE 無法處理收包/回調,需要依賴前置庫(如第三方 GMLIB 已封裝的箱子菜單/虛擬容器接口),或者直接用 C++ 寫原生 mod(C++ 中可配合 iListenAttentively 事件庫的 ReceivePacketEvent 等收包事件處理點擊;iListenAttentively 是 C++ 事件庫,LSE 腳本不能直接監聽它的收包事件)。簡單的按鈕交互一般用表單(Form)代替。

LSE v0.23.1 仍無容器界面 API。

適用版本:LegacyScriptEngine 當前所有版本

LSE 的 setTimeout / setInterval 計時是否受服務器 TPS / tick 速率影響?如何讓定時任務不受影響?

會受影響。LSE 的 setTimeout/setInterval 在服務器主線程上執行,延時會被換算成遊戲 tick 數來調度,因此修改 tick 速率或 TPS 下降時實際觸發時間會隨之變化。在 onTick 裡每 tick 做檢測(如自制 cron)會佔用主線程、影響 TPS,更好的做法是算出距下次觸發的時間再用 setTimeout 調度,耗時操作(如存檔壓縮)放到其它線程/外部進程。

原生 C++ mod 中若不需要與 tick 同步,可用 ll::coro 協程配合 ll::thread::ThreadPoolExecutor 等非 tick 執行器按系統時間等待,需要操作遊戲對象時再切回 ll::thread::ServerThreadExecutor。

適用版本:LegacyScriptEngine 當前所有版本;LeviLamina 當前版本(C++ 部分)

LeviLamina 服務器能運行 / 編寫 Python(以及 Node.js)插件嗎?原來 LLSE 的 Python 插件能用嗎?

可以。LegacyScriptEngine 現已提供 Python 引擎和 Node.js 引擎(早期 LSE 一度不支持,現已不再是問題),用 lip 安裝對應變體即可:lip install LegacyScriptEngine#python(或 #nodejs、#lua、#quickjs;不帶變體時默認安裝 QuickJS 和 Lua 引擎)。LLSE 時期的 Python 插件直接放入 plugins/(自 0.23.0 起該目錄是啟動時創建的指向 mods/ 的鏈接)後啟動服務器會自動遷移(生成 manifest.json),重啟服務器後即可加載,但 Python 插件生態較少。

另一種選擇是寫 Endstone 的 Python 插件:通過 LeviStone(EndstoneRuntime)可在 LeviLamina 上運行 Endstone 插件,這是可選方案。

適用版本:LegacyScriptEngine 0.23.x

新版 LSE 中報錯 找不到事件 onConsoleOutput!In Plugin: xxx(如 TMEssential 在升級 BDS/LSE 後部分功能失效),onConsoleOutput 是被移除了嗎?

是。LLSE 時代有 onConsoleOutput 事件,但新版 LSE 不再提供,維護者表示不會再加回(hook 輸出流給腳本層是糟糕設計)。報錯說明插件太老、使用了已不存在的事件,需要由插件作者刪除對該事件的監聽(mc.listen("onConsoleOutput", ...)),一般不影響插件其他功能。對於 TMEssential 這類已停更的插件,建議換用仍在維護的同類插件(例如 YEssential,home/warp 的 json 數據可按其教程遷移)。

適用版本:LSE 0.10.0 及以上

LSE 能在 LeviLamina 客戶端上運行嗎?怎麼安裝?能用來寫客戶端 mod(按鍵事件、Screen 等)嗎?多人遊戲時會生效嗎?

可以運行,但定位基本是 server only:

  • LSE 在 Windows 客戶端上只在打開本地存檔(單人世界,相當於本地服務端)時運行,用法與服務端相同,服務端的 LSE 插件放到客戶端也能跑。
  • 連接他人服務器進行多人遊戲時腳本不會被激活,LL 的很多服務端 API 在客戶端也不可用。
  • 維護者表示 LSE 不會往客戶端 mod 方向發展,不打算加入按鍵事件、Screen 等客戶端 API;客戶端腳本將來只會考慮另寫新引擎,目前做客戶端 mod 最佳選擇仍是 C++。

安裝:客戶端上用 LeviLauncher 安裝 LeviLamina 與 LSE(LeviLauncher 會自動選用正確的客戶端版本)。LSE 0.23.1 及更早版本的客戶端變體名為 #client_lua / #client_quickjs / #client_nodejs / #client_python;下一個版本起(CHANGELOG [Unreleased],遷移到 lip.toml)不再有 client* 變體,客戶端與服務端都安裝 #lua / #quickjs / #nodejs / #python,由 lip/LeviLauncher 按 side 選取。

只支持 Windows 客戶端,安卓客戶端不支持。

適用版本:LeviLamina 客戶端版(Windows)+ LSE 0.17.0 及以上;變體命名以 LSE 0.23.1 為界

開發 LSE 腳本插件時能否斷點調試?每次查看數據結構都得加輸出再重啟服務器嗎?用 TypeScript 寫時如何定位報錯行?

官方發佈的 LSE 不提供斷點調試器(要實現需自行修改 LSE 源碼重新編譯;且即使服務端暫停在斷點上,客戶端也會因超時斷開)。

  • 常規做法是加日誌輸出後用 ll reload <插件名> 重載插件,無需重啟整個服務器。
  • LSE 還提供交互式命令行用於簡單測試:在 BDS 控制台輸入 jsdebug(QuickJS)、luadebug、pydebug(Node.js 沒有) 進入/退出對應引擎的交互環境。
  • TypeScript 需先用 tsc 編譯為 JS,報錯位置對應的是編譯後的 JS,需藉助 sourcemap 手動對照回 TS 源碼。
  • C++ mod 則可以直接掛 Visual Studio 調試器。

適用版本:LegacyScriptEngine 當前版本(v0.23.1)

LegacyScriptEngine 會長期維護嗎?會有新的腳本引擎(LeviScript)取代它嗎?

早期(2024-02)開發者曾計劃在新腳本引擎 LeviScript 完成後停止維護 LSE,但該計劃已放棄:2024-10 開發者表示新腳本引擎沒人在寫、不會寫,LSE 會繼續存在並維護。

注意 LSE 的 NativeAPI 已被完全移除,不能再在腳本里 call/hook 原生函數。需要更強能力時開發者推薦直接寫 C++ mod;需要 ABI 穩定或想用其他腳本語言寫插件,可考慮第三方的 Endstone。

怎樣把服務器數據(比如排行榜)實時顯示到網頁上?

用插件讀取數據,再通過網絡接口提供給網頁。

  • 可以用 LSE 自帶的 HttpServer(QuickJS/Lua 也可用)或 Node.js 引擎的 http 模塊開一個 HTTP 服務器,網頁用 JS 輪詢。
  • 或者用 WebSocket 推送實現實時刷新。
  • C++ mod 也可以接入 HTTP 庫實現。

適用版本:LSE 當前版本

BDS 服務端插件能給玩家播放音樂嗎?有什麼現成的方案?

可以,常見兩種方案:

  1. 播放 NBS(Minecraft Note Block Studio)格式的音符盒音樂,現成插件如 LLSE-NBSPlayer:https://www.minebbs.com/resources/llse-nbsplayer-bds-nbs.4479/
  2. 把音樂文件打進資源包,再用插件或 /playsound 命令播放對應聲音,缺點是資源包會比較大。

適用版本:當前版本(第三方插件需自行確認兼容性)。未能從源碼或文檔中直接證實,僅供參考。

LL3(LeviLamina + LSE)腳本插件有內置數據庫嗎?需要自己再部署 MongoDB 之類嗎?

有。LegacyScriptEngine 提供數據庫 API:基於 LevelDB 的鍵值數據庫(new KVDatabase(dir)),以及 SQL 數據庫會話 new DBSession(type, params),type 支持 "sqlite3" 和 "mysql"。一般無需額外部署 MongoDB,按需選擇即可(MySQL 需要自備 MySQL 服務)。

適用版本:LegacyScriptEngine 當前版本

LLSE/LSE 裡 setInterval 能做到 1 毫秒執行一次嗎?

不能。LSE 的定時器任務在服務器主線程執行器上調度,延時會向上取整到遊戲刻(1 tick = 50ms),所以精度受 tick 限制,無法做到毫秒級。

另外,如果只是週期性執行命令,用命令方塊或 function 的性能比用腳本 mc.runcmd 好得多。

適用版本:LeviLamina + LegacyScriptEngine 當前版本

LSE 服務器如何查看玩家 IP 並封禁玩家(xuid/IP)?有哪些插件可用?

LSE 提供獲取玩家 IP 的接口:player.getDevice().ip(設備信息對象的 ip 屬性)。

插件方面:

注意封 IP 作用有限,換網絡/熱點即可繞過。

適用版本:LSE 當前版本(第三方插件需自行確認兼容性)。未能從源碼或文檔中直接證實,僅供參考。

LSE 的 API 更新後文檔會同步更新嗎?LSE 還會添加新 API 嗎?

文檔會隨 API 同步更新(https://levimc.org/LegacyScriptEngine/)。

維護者不會再主動給 LSE 添加新功能,現有 API 也基本保持穩定,但歡迎社區提交 PR,新 API 主要通過社區 PR 加入(例如 0.19.1 由社區貢獻加入了 Packet、BinaryStream、mc.getMotd、mc.summonMob 等一批 API)。

適用版本:LSE 當前版本

LSE 的 Node.js 引擎是如何處理插件 package.json 依賴(npm install)並加載插件的?

加載插件時,如果插件目錄下的 package.json 含有 dependencies 字段且插件目錄中還沒有 node_modules,LSE 會先自動執行 npm install --omit=dev --no-fund(使用引擎目錄自帶的 npm),然後創建引擎並加載插件:

  • CommonJS 插件通過一段包裝啟動代碼,修改 require 的查找路徑(加入插件目錄及其 node_modules)後 require 入口文件。
  • package.json 中 "type": "module" 的插件則通過 import() 以 ES 模塊方式加載。

因此其啟動方式不是標準的 node 入口文件 啟動。

適用版本:LSE Node.js 引擎(#nodejs 變體),ESM 支持自 0.10.6 起

LSE 的 getAllPlayerInfo 和 GMLIB 的 LegacyRemoteCallApi(GMLRA)提供的獲取所有玩家信息有什麼區別?

LSE 的 data.getAllPlayerInfo() 讀取的是 LeviLamina 的 PlayerInfo 服務,數據由 LL 自己維護,存放在 LeviLamina 數據目錄下的 playerinfo 數據庫中(存檔外部);GMLRA 調用的是 GMLIB,數據寫在存檔數據裡。LL 作為加載器不應修改存檔數據,所以採用外部存儲。

適用版本:LSE 0.8.13 及以上

LSE 的 Python 引擎和 BDSpyRunner(pyr)有什麼區別?pyr 插件能直接在 LSE Python 上用嗎?

兩者是不同的插件加載器,都支持用 Python 開發插件。LSE 的 Python 引擎(lip install LegacyScriptEngine#python)與其他 LSE 引擎(Lua/QuickJS/Node.js)共用同一套 API,pyr 的插件不能直接通用,需要按 LSE 的 API 改寫。

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

適用版本:LSE 當前所有版本

LSE 腳本插件能否在事件監聽裡修改事件數據,比如把玩家攻擊造成的 5 點傷害改成 10 點?

不能直接修改。LSE 的 mc.listen 事件回調只能讀取參數,或者對可攔截的事件返回 false 來取消該事件,不能改寫事件裡的數據(例如 onMobHurt 的 damage)。如果確實需要修改事件數據,請用 C++ 編寫 LeviLamina mod。

在腳本里能做的變通辦法是:先攔截原事件,再自行調用相應 API 重新施加效果(例如取消原傷害後對實體調用 hurt 造成新的傷害),但這與真正修改事件並不等價。

適用版本:LegacyScriptEngine 當前所有版本(至 v0.23.1)

LSE(LLSE)插件能否實現 JSON UI / ORE UI 這類自定義界面,而不只是表單?

不能。LSE 的 GuiAPI 只提供服務端表單(SimpleForm / ModalForm / CustomForm,以及 FormBuilder),目前沒有封裝 DDUI 等新版界面 API。JSON UI 這類自定義界面必須由客戶端資源包實現。

可行的做法是:編寫原版 addon(資源包/行為包)來提供界面,再與 LSE 插件通過約定的信道(例如特定的表單標題或內容標記、scriptevent、記分板等)聯動。

適用版本:LegacyScriptEngine 當前版本(v0.23.1)

LegacyScriptEngine 是否支持 MySQL 數據庫?舊的 NativeApi(dyncall)還能用嗎?SQLite 是否可用?

LSE 從 0.9.0 起恢復了 MySQL 支持(底層改用 mariadb-connector-c),通過 DBSession 使用:type 為 "mysql",或使用 mysql://root:password@localhost:3306/db 形式的連接串。0.9.0 發佈時 Node.js 引擎不支持 MySQL;目前源碼已不再按後端區分,但 Node.js 引擎下是否可用請以實際版本為準。

SQLite("sqlite3")一直可用,從未被移除。

NativeApi 已在 0.8.19 中被完全移除,不會恢復,依賴 dyncall/NativeApi 的舊插件無法使用。

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

LegacyScriptEngine 是否有可以在服務器控制台裡直接執行 JS/Lua 代碼的命令?OP 能否藉此在服務器裡“新建插件”?

有。QuickJS 引擎提供 jsdebug,Lua 引擎提供 luadebug。不帶參數執行會進入/退出交互調試模式,在控制台逐行執行代碼(輸入 stop 或再次執行該命令即可退出);也可以用 jsdebug <代码> 直接執行一段代碼。Python 引擎使用 pydebug,僅在控制台中處理;Node.js 引擎沒有調試命令。

注意:該命令的權限由 LSE 配置文件(mods/legacy-script-engine-xxx/config/config.json)裡的 debugCommandLevel 決定,默認值為 GameDirectors,也就是 OP 默認就能在遊戲內執行。能執行任意代碼就等於拿到服務器後臺權限,非常不安全,建議把 debugCommandLevel 調高(例如 Owner/Host)只留給控制台使用。如果需要給遊戲內管理員提供特定功能,應自己寫插件註冊專用命令。

適用版本:LSE 當前版本(v0.23.1);debugCommandLevel 配置項為較新版本新增

LegacyScriptEngine 的 QuickJS/NodeJS/Python/Lua 各引擎是分開的源碼嗎?它是怎麼實現多語言支持的?

LSE 只有一套源碼(https://github.com/LiteLDev/LegacyScriptEngine),通過 xmake 的 backend 配置(lua / quickjs / python / nodejs)把同一份源碼編譯成四個引擎:legacy-script-engine-lua、-quickjs、-python、-nodejs。

多語言支持基於 ScriptX(最初由騰訊開源的多腳本引擎封裝層,LiteLDev 維護著自己的 fork),層次為 LSE -> ScriptX -> QuickJS / Node.js(V8) / Python / Lua。LSE 是 LLSE 的移植版,每個插件分配一個獨立的 ScriptEngine 實例。

適用版本:LegacyScriptEngine 當前所有版本

LegacyScriptEngine 裡有 nodejsdebug 命令嗎?

沒有可用的 nodejsdebug。源碼裡雖然為 Node.js 後端定義了 nodejsdebug 這個名字,但 Node.js 引擎不支持調試引擎,不會註冊該命令。可用的調試命令是 QuickJS 的 jsdebug、Lua 的 luadebug,以及 Python 的 pydebug(僅限控制台)。

適用版本:LSE 當前版本(v0.23.1)

iLand 領地插件如何設置領地管理員?

在服務器控制台執行 land op <玩家名>,該玩家必須至少進入過服務器一次。iLand 是 LLSE 腳本插件,需配合 LegacyScriptEngine 運行。

適用版本:使用 iLand 腳本插件的服務器(第三方插件)。未能從源碼或文檔中直接證實,僅供參考。

為什麼 LSE 提供的一些事件在 LeviLamina C++ 中找不到對應的事件,C++ 插件要怎麼實現同樣的監聽?

LeviLamina 只保留了少量核心事件,LL2 時代的大量事件沒有搬進 LeviLamina。LSE 為保持對 LLSE 插件的兼容,自己補齊了這些事件:一部分基於事件庫 iListenAttentively(LSE 的依賴),一部分在 LSE 內部自己 hook 實現。所以 LSE 事件並不與 LeviLamina 事件一一對應。

C++ mod 想實現同樣的監聽,可以依賴 iListenAttentively(lip install github.com/LiteLDev/iListenAttentively)使用其事件,或者自己寫 hook。

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

在 LegacyScriptEngine 中,一個 JS 插件裡定義的全局變量/Map 等數據會不會干擾服務器上其他腳本插件?

不會。LSE 為每個腳本插件創建獨立的腳本引擎實例,各插件有獨立的全局作用域,彼此變量不會互相干擾。插件間需要共享數據或調用函數時,使用遠程調用 ll.exports / ll.imports(由 LegacyRemoteCall 提供)等機制。

如何查看已安裝的 LegacyScriptEngine(LSE)版本?

在控制台執行 ll show <mod名>(例如 ll show legacy-script-engine-quickjs,引擎包名按語言為 legacy-script-engine-quickjs / -lua / -nodejs / -python)查看該 mod 的信息和版本;也可用 ll list 列出所有已加載的 mod 及版本。

適用版本:LeviLamina 0.13 及以上

如何給 LSE 添加新的腳本語言支持(例如 PHP)?

LSE 的腳本語言支持由底層 ScriptX 提供,新增語言需要 ScriptX 先有該語言的後端,再在 LSE 中增加對應的引擎變體,不能簡單地在 LSE 裡直接加。目前 LSE 提供 lua、quickjs、nodejs、python 四種引擎。

懷疑服務器被後門插件執行了命令,但控制台沒有命令記錄,怎麼排查?

LSE 的 mc.runcmdEx(以及 mc.runcmd)以服務器身份執行命令,輸出被捕獲返回給腳本而不會打印到控制台,所以控制台看不到記錄很正常。應檢查插件列表,並在插件源碼中搜索 runcmdEx、runcmd、setInterval 等關鍵字排查可疑腳本。

新手想寫一個由 LeviLamina 加載的插件,應該從哪裡開始?需要下載 LeviLamina 源碼嗎?

不需要改 LeviLamina 源碼。新手建議先寫 LegacyScriptEngine(LSE)腳本插件:

寫代碼前先引入 API 類型提示:在項目裡執行 npm install -D @levimc-lse/types,並在 tsconfig.json 的 compilerOptions.types 中加入 "@levimc-lse/types"(或在入口文件寫 /// <reference types="@levimc-lse/types" />),這樣多人協作時也不會有絕對路徑衝突。

想寫原生 mod 則需學習 C++ 並配置 VS/xmake 環境(參考 LeviLamina 文檔和 levilamina-mod-template)。

新版 LSE 每次開服都會自動生成一個 plugins 快捷方式(目錄鏈接),刪掉還會再生成,這是什麼?複製到另一臺機器後變成了普通文件夾/鏈接失效怎麼辦?

這是預期行為:大部分 LSE 插件硬編碼了 plugins 路徑,所以 LSE 0.23.0 起會在開服時創建指向 mods/ 的目錄鏈接(Windows 上為 junction)來保證兼容。

目錄鏈接使用絕對路徑,把整個服務端文件夾複製到其他機器會使鏈接損壞,刪掉它讓 LSE 重新自動生成即可。注意如果 plugins 位置已存在同名普通文件/文件夾且不指向 mods,LSE 會報錯而不會覆蓋。

適用版本:LSE 0.23.0 及以上(LeviLamina 26.60)

有沒有能在 Endstone 上運行 LSE(LegacyScriptEngine)插件的插件?

沒有。LSE 是 LeviLamina 的模組(native 類型),依賴 LeviLamina 及 LegacyMoney、LegacyRemoteCall、iListenAttentively 等前置,只能運行在 LeviLamina 上(服務器用 lip 安裝,客戶端用 LeviLauncher 安裝)。網上/AI 所說的“Element Zero 兼容 LSE”之類說法不可信。

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

服務器裡玩家死亡消息顯示為“被蓄意的遊戲設計殺死”(Intentional Game Design)之類,是外掛嗎?原因是什麼?

一般不是外掛。原版中“蓄意的遊戲設計”是床/重生錨爆炸致死的死亡消息;另外,插件用 LSE 的 en.hurt(damage[,type[,source]]) 等接口造成傷害且未指定傷害來源時,也可能出現非常規的死亡消息。可排查是否有人在下界/末地用床或重生錨,以及哪個插件在對玩家造成傷害。

死亡消息文本取決於 BDS 原版行為。

適用版本:LSE 當前版本。未能從源碼或文檔中直接證實,僅供參考。

用 LSE 寫 JS 插件是否必須安裝 Node.js / nodejs 引擎?

不需要。普通 JS 插件由 QuickJS 引擎(lip install github.com/LiteLDev/LegacyScriptEngine#quickjs,不帶變體時默認同時安裝 QuickJS 和 Lua 引擎)運行,直接放入的單個 .js 文件會被識別為 quickjs 插件,遷移後 manifest.json 中 type 為 lse-quickjs。

只有需要 Node.js API 或 npm 包時,才需要安裝 #nodejs 引擎,此時 manifest 的 type 為 lse-nodejs。

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

編寫 LSE(LLSE)JS 插件時,文件開頭那行引用類型定義的註釋(/// <reference ...>)在編輯器裡報紅線,需要修復嗎?會影響插件運行嗎?

不影響運行。那行只是給編輯器提供類型信息和代碼補全的三斜線註釋,報紅只是找不到對應的類型定義。

需要補全可按 legacy-script-engine-api 的說明安裝 @levimc-lse/types,然後在入口文件寫 /// <reference types="@levimc-lse/types" /> 或在 tsconfig.json 的 compilerOptions.types 中加入它;不需要就可以不管。

若插件運行時後臺反覆報錯,與這行註釋無關,應檢查其他原因(如 JSON 配置文件格式錯誤、前置插件缺失或損壞,可重裝前置)。

能用 LSE(如 NativeCall/NativeAPI)在腳本插件裡 hook 遊戲函數嗎?

不能,也不建議。LSE 的 NativeAPI 已在 0.8.19 被完全移除,腳本插件無法 hook 遊戲函數。如需 hook,請直接用 C++ 編寫 LeviLamina 模組(可基於 levilamina-mod-template)。

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

覺得用 C++ 開發 LeviLamina 原生 mod 門檻太高,有沒有更簡單的開發方式?

可以使用 LegacyScriptEngine(LSE),用 JavaScript(QuickJS/Node.js)、Lua 或 Python 開發插件,相對簡單,服務器和 Windows 客戶端都可運行。

在 LSE 中熱卸載了註冊過命令的腳本插件後,關服時服務器崩潰,為什麼?

原版命令系統不支持註銷命令。插件卸載後命令仍留在命令註冊表中,但回調所在的插件已不存在。當前版本的 LSE 在執行此類命令時會輸出警告 Command xxx failed to execute, is the plugin unloaded? 而不再執行回調;但仍建議註冊了命令的插件不要熱卸載/重載,需要更新時重啟服務器更穩妥。

適用版本:LeviLamina + LSE,當前所有版本(關服崩潰是否仍會發生未確認)。未能從源碼或文檔中直接證實,僅供參考。

LeviLamina 下用 JS/Lua 等腳本寫插件時(LegacyScriptEngine,原 LLSE),API 文檔在哪裡?LeviLamina 主文檔裡為什麼找不到?舊的 LiteLoaderBDS / lse.liteldev.com / lse.levimc.org 文檔打不開怎麼辦?

腳本插件由 LegacyScriptEngine(LSE)提供,它只是 LeviLamina 的一個模組,所以 LeviLamina 主文檔只講 C++ 模組開發,腳本 API 文檔在 LSE 自己的文檔裡。當前地址:https://levimc.org/zh-Hant/LegacyScriptEngine/(英文 https://levimc.org/LegacyScriptEngine/),API 索引在 https://levimc.org/zh-Hant/LegacyScriptEngine/apis/(例如 Logger:/zh-Hans/LegacyScriptEngine/apis/ScriptAPI/Logger/,事件:/apis/EventAPI/Listen/)。入門可看官方教程“寫你的第一個腳本插件”:https://levimc.org/zh-Hant/tutorials/develop/first-script-plugin/。

歷史上用過的 docs.litebds.com、lse.liteldev.com、legacy-script-engine.levimc.org、lse.levimc.org、docs.levimc.org/LegacyScriptEngine 都已是舊地址,以 levimc.org 上的為準;舊 LiteLoaderBDS 文檔存檔在 https://liteldev.github.io/liteloaderbds-documentation/,僅供參考。

新版 JS API 與舊版 LLSE 基本一致,但網上很多 LL v2 時代的教程有些步驟已不需要:插件信息改由插件目錄中的 manifest.json 聲明(ll.registerPlugin() 仍可調用但不再是必需)。簡單示例:

js
mc.listen("onJoin", (player) => {
    log(`${player.name}已经加入服务器。`);
    player.sendToast('欢迎!', '感谢您游玩本服!');
});

適用版本:LSE 當前所有版本

LSE 插件 ll reload 後命令失效或反覆報錯(如命令註冊失敗),該怎麼辦?

用假命令(mc.regPlayerCmd / mc.regConsoleCmd 等舊接口)註冊的命令只會在服務器啟動完成(onServerStarted)時統一註冊一次,插件 reload 後重新調用這些接口不會再被註冊,因此命令會失效。文檔已不推薦假命令,應改用真命令 mc.newCommand:reload 時若命令已存在,只會提示 Runtime command ... already exists,並重新應用 setOverload / setCallback,命令可繼續使用。熱加載/卸載本為調試而生,存在風險和性能問題,生產環境遇到問題直接重啟服務器更可靠。

適用版本:LeviLamina 當前版本;LegacyScriptEngine 當前版本

LSE 有 Markdown 格式的文檔嗎(比如想餵給 AI)?

有。LSE 文檔站由 Markdown 源碼生成,源碼在 GitHub 倉庫 LiteLDev/liteldev.github.io 的 docs/LegacyScriptEngine/content 目錄下(中文為 *.zh.md,英文為 *.md,API 文檔在 apis/ 子目錄)。另外 LiteLDev/legacy-script-engine-api 倉庫提供插件開發的 API 類型提示,也可作為參考。

LSE 的 Python 引擎插件一直報錯,有什麼替代方案?

開發者建議:與其使用 LSE 的 Python 引擎(LegacyScriptEngine#python),不如使用 LeviStone——它是在 LeviLamina 上運行 Endstone 插件的運行時,可使用 Python 生態。安裝方式:在裝好 LeviLamina 的 BDS 目錄下執行 pip install levistone --target mods/EndstoneRuntime(0.11.15 之前的版本目標目錄為 plugins/EndstoneRuntime)。

適用版本:LeviLamina 當前版本;LeviStone 0.11.15 及以上

升級服務端後,iLand 領地插件裡領地主人顯示成“?”,怎麼辦?

這是升級(換新服務端目錄)時沒有把 LeviLamina 的玩家信息數據(PlayerInfo,用於 xuid 與玩家名互查)拷過來導致的。可以從舊服務端把 mods/LeviLamina/data/playerinfo 目錄拷到新服務端,或者等對應玩家重新上線後自動更新。此問題影響依賴 data.xuid2name 等接口的插件。

適用版本:LeviLamina 當前版本;LegacyScriptEngine 當前版本

在 LSE JS 插件裡把 setTimeout/setInterval 的定時時間等數值設成 99999999999 這樣很大的數,會不會出問題?

會。LSE 讀取定時器時間時按 32 位有符號整數轉換(toInt32),超過 2147483647 會溢出成別的值,若變成 ≤0 還會被當作 1 毫秒立即執行。除非清楚會發生什麼,否則傳給 LSE API 的整數參數都建議小於 2147483648(2^31)。

適用版本:LegacyScriptEngine 當前版本

想在網頁上同步顯示服務器的動態地圖,有什麼插件?

這類功能屬於網頁地圖插件,可以去 MineBBS 搜索“衛星地圖”等關鍵詞,選擇支持當前 LeviLamina/BDS 版本的插件。第三方插件需自行確認是否支持當前版本。

適用版本:當前版本(第三方插件)。未能從源碼或文檔中直接證實,僅供參考。