跳到正文
本頁目錄

LegacyScriptEngine 的性能與開發工具

LSE 中的異步是真正的異步嗎?做大量計算會不會卡主線程?

不是真正的多線程異步。LSE 的腳本引擎事件循環在 MC 服務器主線程上執行:QuickJS/Lua 等引擎的消息隊列每 tick 輪詢一次(loopQueue kLoopOnce),Promise/setTimeout 等只是推遲到主線程後續執行;QuickJS 的微任務(Promise 回調)由 ScriptX 投遞到引擎消息隊列中執行;Node.js 引擎的 libuv 事件循環和微任務也是由 LSE 在主線程上約每 2 tick 驅動一次(uv_run NOWAIT)。所有 MC API 都是同步調用。

因此大量計算無論是否寫成 async 都會卡住主線程(造成 TPS 下降)。建議把計算拆成小塊分 tick 執行;使用 Node.js 引擎時也可嘗試把純計算放到 worker_threads 的 worker 裡(worker 中不能調用 MC API,此用法官方文檔未說明)。Python 引擎文檔明確要求暫時不要使用 threading、asyncio 等特性。

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

LSE 的 quickjs 引擎和 nodejs 引擎有什麼區別,用的是 V8 嗎?性能如何比較?

QuickJS 引擎(LegacyScriptEngine#quickjs)使用 QuickJS 作為 JS 引擎,不是 V8;Node.js 引擎(LegacyScriptEngine#nodejs)才使用 V8,並支持 npm 包。QuickJS 與 Python 引擎性能高下不一定,V8 是知名的高性能(JIT)引擎;大型項目可以考慮用 Node.js 引擎。

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

LSE(原 LLSE)腳本插件能用多線程來提升窮舉(如搜索附近礦石)的性能嗎?

基本不能。LSE 的腳本 API 都只能在服務器主線程上調用,腳本引擎本身(QuickJS、Lua)沒有可用的多線程;即使 Node.js 的 worker_threads 或 Python 線程能跑純計算,也無法在其中調用 LSE/BDS 接口,多進程同樣無法與 BDS 交互。需要高性能計算(大範圍窮舉方塊等)時應改用 LeviLamina 原生 C++ mod,或把計算降頻、分批到多個 tick 執行。

適用版本:LegacyScriptEngine 當前所有版本(含 0.23.1)。未能從源碼或文檔中直接證實,僅供參考。

LSE JS 插件在 mc.listen("onTick") 中每 tick 讀寫文件,導致玩家進服變慢、服務器卡頓,如何排查和優化?

用 VS 性能分析(火焰圖)等工具可以看到大量文件讀寫。在插件裡搜索 File.readFrom / File.writeTo 找到在 onTick 中讀寫文件的代碼。每 tick 寫一次文件等於每秒 20 次磁盤 IO,比 BDS 存檔寫入頻率還高,性能影響很大。應改為幾秒寫一次(或數據變化時再寫);很多場景不需要監聽 onTick,可以用 setInterval 作為低頻版的 tick 定時器。

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

LSE 插件需要大量修改方塊(例如清空區塊)時,用 mc.setBlock 逐個設置還是用 fill 命令更好?

在 LSE 中大量逐個調用 mc.setBlock 的開銷(每次都要跨腳本/C++ 調用並構造方塊)比直接執行一次 fill 命令更大;大範圍修改優先用 fill(注意 fill 需要目標區塊已加載,且單次體積有上限),或考慮加載結構等方式。

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

LSE 的 KVDB(KVDatabase)讀取很快,但寫入嵌套對象/字典時很卡,為什麼?怎麼優化?

KVDatabase.set 會把傳入的值通過 ValueToJson 轉成 JSON:如果傳的是對象/數組,LSE 需要遞歸遍歷每個鍵、逐個從腳本引擎取值並轉換,嵌套越深越大就越慢;直接傳字符串則只做一次取值,快得多。建議自己先把數據序列化成字符串(例如 JSON.stringify,或 NBT 直接序列化為 SNBT/二進制字符串)再存。LevelDB 本身內部已有讀寫緩存,瓶頸通常在序列化上,不必再自己做一層讀寫緩存。

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

LSE 自帶的 BossBar 接口(player.setBossBar)有什麼問題?為什麼設置 bossbar 時指定的實體會消失?

帶 uid 的 player.setBossBar(uid, title, percent, color) 實現是:先發 BossEvent Remove,再發一個 AddActor 數據包(ActorType 為 "player",uniqueId/runtimeId 都用傳入的 uid,位置放在維度最低高度以下),再發 BossEvent Add。也就是每次更新都是刪除後重新添加,而不是發送更新包;如果傳入的 uid 是一個真實存在的實體,客戶端會被這個假實體覆蓋,所以看起來指定實體消失了。頻繁更新時開銷也較大,另有反饋稱其構造 AddActor 的方式會與其他插件(如 LeviOptimize)的多線程發包衝突。

需要頻繁更新 bossbar 時,可改用 GMLIB 等庫提供的發送/更新實現(建議調用其導出接口而非照抄),或使用一個不存在的 uid。

適用版本:LegacyScriptEngine 當前所有版本(0.23.1 實現未變)

LSE 中大量使用時,執行原版命令(mc.runcmd / mc.runcmdEx)和調用等價的腳本 API,哪個性能更好?

一般用 API 更好:API 能省去命令字符串解析和命令執行流程的開銷,而其背後調用的遊戲邏輯和命令基本是同一套。

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

LeviLamina 服務器裝了七八十個插件(大量 LSE 腳本插件 + addon),高端 CPU 十幾個玩家 TPS 只有個位數,怎麼優化?

LSE 插件越多服務器越卡:C++ 與腳本層之間的通信本身就耗時,插件越多開銷越大。建議:

  1. 刪掉不必要的 LSE 插件,能用 LeviLamina 原生 C++ mod 替代就替代(如領地用 C++ 的 PLand 代替 Lua 的 iLand)。
  2. 只安裝需要的腳本引擎變體:用 lip install LegacyScriptEngine#quickjs(或 #lua、#nodejs、#python)按需安裝,不指定變體時會同時裝 QuickJS 和 Lua,用不上的引擎可以卸掉。
  3. 完全不裝 LSE 時性能最好,再配合 LeviOptimize 更好。
  4. 記錄玩家行為的日誌類插件(如 BehaviorLog)對性能很敏感,容易造成卡頓。
  5. 大型生物 addon、大量村民/刷鐵機也會顯著拉低 TPS。

案例中刪掉大量插件和高負載 addon 刷怪規則後,十多人 TPS 回到 17+。

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

為什麼說 LL2 的腳本引擎會拖慢服務器?現在的 LSE 在這方面有何不同?

LL2(LiteLoaderBDS)中只要存在腳本插件就會啟動全部腳本引擎(JS/Lua/Node/Python),並不按需啟動,讓性能本就一般的 BDS 更卡。LeviLamina 下的 LSE 將各引擎拆分為獨立變體,需要哪個裝哪個:lip install LegacyScriptEngine#quickjs / #lua / #nodejs / #python;不指定變體時默認同時安裝 QuickJS 和 Lua。不需要的引擎不裝即可減少開銷。

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

同樣數量的循環調用下,LSE 腳本和原版 Script API(addon 腳本)哪個更快、更不容易掉刻?

兩者都是在服務器主線程執行 JS,單純的腳本運算性能差別不大,主要差異在於 C++ 與腳本之間互調的開銷;無論哪種都應儘量避免在 tick 中做大量循環,可把工作分批到多個 tick 或降低頻率。另外原版 Script API 的 before 事件中不允許修改世界狀態時,可以用 system.run 等計劃任務把操作放到下一 tick 執行。

適用版本:LegacyScriptEngine 當前版本;原版 Script API 行為取決於 BDS。未能從源碼或文檔中直接證實,僅供參考。

在 LSE 中調用 GMLIB 的懸浮字 API 會很消耗性能嗎?

取決於實現方式:如果是生成真實實體的懸浮字會比較耗性能;GMLIB 的懸浮字是發包實現的(客戶端假實體),服務端開銷較小。

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

服務器 20 人左右 TPS 只有 10 左右,性能分析顯示大量時間在漏斗和 LSE(QuickJS)插件上,是什麼原因?

原因是裝了監聽漏斗事件(onHopperSearchItem / onHopperPushOut)的 LSE 防刷物類插件,且服務器裡漏斗很多:每個漏斗每秒會多次觸發這些事件,插件在每次事件回調裡都執行一堆邏輯,導致嚴重卡服。解決辦法:卸載/替換該防刷物插件,或者減少漏斗數量。

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

用 LSE 做礦區刷新時,除了用 for 循環逐個 setBlock,有沒有性能更好的方法?

可以預先把礦區做成結構(NBT structure)保存好,刷新時用 mc.setStructure(nbt, pos, mirror = 0, rotation = 0) 一次性放置整個結構。相比在腳本里循環逐個 mc.setBlock,一次性放置結構的開銷更小。

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

用 LSE 插件通過頻繁 rename 玩家名,在名字下方顯示延遲等信息後,玩家進服會卡幾秒,原因是什麼?

pl.rename() 不只是改名:它會調用 setNameTag 並把實體的 ActorData(SetActorDataPacket)重新同步給所有玩家,每調用一次就發一次。如果每 tick 給所有玩家 rename,會產生大量數據包,可能擠佔/延後正在進服玩家的區塊包,導致加載卡頓,同時 rename 還會影響命令輸出等顯示名。

更好的做法是:用 LSE 的發包接口(BinaryStream 構造數據包後 pl.sendPacket(packet))只發給需要的玩家,或在 C++ 中 hook 相關數據包修改顯示名,並降低更新頻率,而不是頻繁 rename。

適用版本:LegacyScriptEngine 當前版本

用性能分析工具(如 Visual Studio 診斷 .diagsession)分析 LeviLamina 服務器卡頓時,看不出是哪個插件佔用高,怎麼辦?哪些 LSE 插件容易影響性能?

原生 DLL 插件需要配套的 .pdb 符號文件才能在分析中看到函數名:檢查每個 dll 插件目錄下是否有對應的 pdb,沒有就去插件下載頁獲取並放進插件文件夾;pdb 必須與插件實際版本一致,否則仍無法解析。

對於 LSE 腳本插件,分析器(包括 windbg)只能看到 LSE 引擎本身,無法區分具體是哪個腳本插件。若調用棧熱點在 tick 中,說明與 onTick 有關,可在插件目錄的 *.js 文件中全局搜索 onTick(如用 VSCode/Notepad++),找出 mc.listen("onTick", ...) 的插件;監聽 onTick 的 LSE 插件(如 TMEssential)都會帶來持續開銷,LSE 本身加載也有一定開銷。

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

LSE nodejs 引擎長時間運行(約 18 小時)後報 JavaScript heap out of memory 導致崩服,內存限制能調嗎?

舊版 LSE nodejs 使用 Node 16,新版使用 Node 22。堆內存由 Node/V8 管理並有上限,理論上可通過 Node 啟動參數 --max-old-space-size 調大(LSE 本身沒有提供配置項傳入該參數,可嘗試在啟動 BDS 前設置環境變量 NODE_OPTIONS=--max-old-space-size=<MB>,未經官方確認)。不過此類問題多半是插件隨時間不斷創建對象未釋放(內存洩漏)造成,應優先排查插件;臨時辦法可以定時重載插件。

適用版本:LSE nodejs 引擎(Node 22)當前版本

寫 LSE(原 LLSE)JS/TS 插件時,有沒有官方的類型定義(.d.ts)/代碼補全庫?HelperLib、LiteLoaderSE-Aids 還能用嗎?

有。官方類型定義由 LiteLDev/legacy-script-engine-api 倉庫維護(原 HelperLib 倉庫已改名為它,舊鏈接 github.com/LiteLDev/HelperLib 會跳轉過去),JS/TS 平臺以 npm 包 @levimc-lse/types 發佈:

  1. 在插件項目中執行 npm install -D @levimc-lse/types。
  2. 在 tsconfig.json(或 JS 項目的 jsconfig.json)中加 "compilerOptions": { "types": ["@levimc-lse/types"] },或在入口文件頂部寫 /// <reference types="@levimc-lse/types" />。

注意:截至 2026-11-18,npm 官方源 registry.npmjs.org 上 @levimc-lse/types 返回 404(yarn 源、jsDelivr 也取不到),國內鏡像 npmmirror 仍保留 2.18.7。若官方源安裝失敗,可用 npm install -D @levimc-lse/types --registry=https://registry.npmmirror.com,或直接從 legacy-script-engine-api 倉庫 platforms/javascript/src 複製 .d.ts,並用 /// <reference path="本地路径/index.d.ts" /> 引用。

舊寫法 /// <reference path="node_modules/helperlib/src/index.d.ts"/> 已過時;reference path 只能指向本地文件,不能寫 URL。該倉庫也提供 Python 平臺的提示庫。

VSCode 擴展 LiteLoaderSE-Aids 本質只是一鍵引入補全並可選 BDS 目錄開服,官方倉庫已歸檔不再維護(社區有魔改版 LiteLoaderSE Aids Magic Revision,另有第三方擴展如 LLScriptHelper-MR、社區 npm 包 levilamina 等,均非官方)。

不用擴展也可以測試:在 VSCode 終端 cd 到服務端目錄,PowerShell/cmd 下運行 .\bedrock_server_mod.exe(Git Bash 下 ./bedrock_server_mod.exe)即可。

LSE 的公共 API 與舊 LLSE 基本一致,舊 LL v2 時代的聲明大體可用,但建議以官方 @levimc-lse/types 為準。

適用版本:當前版本;@levimc-lse/types 2.18.x

LSE 能直接加載 TypeScript 嗎?用 TS 寫 LSE 插件 tsconfig 怎麼配,多文件項目怎麼打包成一個插件 js?

LSE 不支持直接加載 .ts,也不做即時編譯,需要先編譯/打包成 JS 再加載(可用 tsc --watch 或打包器)。

類型用官方包 @levimc-lse/types(截至 2026-11-18 npm 官方源返回 404,可加 --registry=https://registry.npmmirror.com 安裝,或從 legacy-script-engine-api 倉庫 platforms/javascript/src 取 .d.ts),在 tsconfig.json(文件名必須是 tsconfig.json)中設置 "types": ["@levimc-lse/types"]。部分類型聲明是全局聲明、沒有默認導出,不要去 import 它們,直接使用全局的 mc、ll、log 等即可。

多文件項目可用打包器合併為單個文件,例如社區模板 dmblock/lse-typescript-template(rolldown):

  • tsconfig 關鍵項:"target": "es2024"、"module": "commonjs"、"moduleResolution": "node"、"esModuleInterop": true、"skipLibCheck": true、"types": ["@levimc-lse/types"]、"rootDir": "./src"、"outDir": "./dist"。
  • rolldown.config.ts:defineConfig({ input: 'src/index.ts', output: { file: 'dist/bundle.js', format: 'cjs' }, external: ['ll', 'mc'], platform: 'node', tsconfig: './tsconfig.json' })。
  • 使用方法:git clone https://github.com/dmblock/lse-typescript-template 後刪除 .git,執行 pnpm install,pnpm dev 監聽開發、pnpm build 構建,把 dist/bundle.js 改名放進插件目錄(配 manifest.json)。

只 import 不使用的模塊會被 tree-shake 掉。

另外,QuickJS 引擎原生支持 ES Module 的 import/export(入口模塊相對路徑解析有特殊行為,見文檔 LanguageSupport);若用 Node.js 引擎,則按 npm 項目打包,package.json 入口指向編譯後的 js,node_modules 不要打進壓縮包。

如何在 Windows 上編譯 LSE 所用的 libnode.dll(網上教程多是 .so)?

在 node 源碼目錄執行 .\vcbuild.bat dll。如果要像 LSE 一樣用到 v8 內部的東西(如 v8_libplatform),還需修改 tools/v8_gypfiles/v8.gyp,參考 https://github.com/LiteLDev/node/commit/80d31fc05ed413e3b29fbbdb0a4dc380eab2f5e3。

LSE 實際使用的是 LiteLDev/node fork 的預編譯包(當前為 v22.12.0),一般無需自行編譯。

適用版本:當前版本(LSE nodejs 後端,Node.js v22.12.0)

用 TypeScript 寫 LSE 插件時,LSE 提供的 File 類與 JS/DOM 內置的 File 衝突報錯,怎麼解決?

衝突來自 TypeScript 默認 lib 中 DOM 自帶的 File 類型。在 tsconfig.json 中顯式設置 "lib",只寫 ES 版本(如 ["ES2020"]),不要加 "dom",LSE 的 File 聲明即可生效;可配合 "skipLibCheck": true。

類型聲明可用 npm install -D @levimc-lse/types 並在 compilerOptions.types 中加入 "@levimc-lse/types"。如果用的是 Node.js 引擎,也可以直接用 Node 的 fs 模塊。

適用版本:當前版本(JS/TS 插件開發)