LegacyScriptEngine API:世界與方塊
LSE 插件在全局作用域獲取/創建計分板對象(如 mc.getScoreObjective、mc.newScoreObjective),ll reload 後正常,但服務器重啟後報錯或得到 null,為什麼?
插件加載時服務器(世界)尚未啟動完成,此時無法操作計分板等原版內容,獲取到的對象為 null。應在全局用 let 聲明變量,然後在 mc.listen("onServerStarted", () => { /* 在这里获取/创建计分板 */ }) 回調裡再賦值,使用前做非空判斷。熱重載(ll reload)時服務器已啟動,所以能直接拿到;且 LSE 對服務器啟動後才加載的插件也會補發 onServerStarted,因此統一寫在該事件裡兩種情況都適用。
適用版本:當前所有 LSE 版本
LSE 腳本中如何判斷某個區塊是否已加載?等待區塊加載時用 while/for 循環檢測導致服務器假死怎麼辦?
用 mc.getBlock(x, y, z, dimid) 讀取該位置方塊:區塊未加載時返回 null(不會拋錯),返回方塊對象即已加載;訪問屬性前先判空。
不能用同步循環(while/for)反覆檢測:LSE 所有邏輯都在服務器主線程(tick 線程)上執行,忙等會阻塞主線程,區塊永遠加載不了,服務器假死、玩家卡在空中。正確做法是用定時器:setInterval 定期檢測(保存 timer id,成功後 clearInterval 並執行回調),或 setTimeout 延遲重試。區塊加載是異步的,耗時不確定。
隨機傳送/假人場景:可先把玩家或模擬玩家傳送到目標 x/z 的高空,再用定時器檢測 mc.getBlock 是否不為 null,或檢測其 y 座標是否開始變化(玩家在未加載區塊會懸停,加載後才下落),再確定落點/執行操作。C++ mod 中可直接檢查區塊是否已完全加載後再操作。
適用版本:LeviLamina 上的 LegacyScriptEngine 當前所有版本
LSE 的 mc.setBlock 能否在未加載的區塊裡設置方塊?
不能,目標區塊必須處於加載狀態(未加載時 mc.setBlock 會返回 false)。變通方法:先讓區塊加載起來,例如用 mc.spawnSimulatedPlayer 在該處生成模擬玩家(假人),區塊加載後再放置方塊,完成後讓假人退出;C++ mod 則可以先強制加載區塊再操作。
適用版本:LeviLamina 上的 LegacyScriptEngine 當前所有版本
LSE 中 mob.pos 打印出來是“主世界(x,x,x)”這樣的字符串,對它用 replace 報 cannot read ... from 'undefined',如何獲取座標數值來生成粒子?
pos 不是字符串,而是 FloatPos/IntPos 對象,打印出的友好格式是其 toString 的結果。不要做字符串處理,直接讀取屬性 pos.x、pos.y、pos.z 和 pos.dimid 即可,也可直接把 pos 傳給 API(例如 ps.spawnParticle(pos, name))。建議先閱讀文檔中的基礎類型說明,使用 TypeScript 類型聲明可避免此類錯誤。
適用版本:LegacyScriptEngine 當前所有版本(原為 LLSE)
LSE 中 mc.setBlock 的 block 參數傳入 NBT 對象時提示參數錯誤,怎麼回事?
傳 NbtCompound(或 Block 對象)時不要再傳 tileData 參數,兩者是不同的重載:
mc.setBlock(pos, blockObject)/mc.setBlock(x, y, z, dimId, blockObject)接受 Block 或 NbtCompound;mc.setBlock(pos, blockString, tileData)/mc.setBlock(x, y, z, dimId, blockString, tileData)只在 block 為方塊類型名字符串時可帶tileData。
帶了 tileData 時 LSE 會要求 block 參數必須是字符串,否則報參數類型錯誤。TypeScript 聲明庫 legacy-script-engine-api 已在 JavaScript@v2.17.0(2025-06-20)修正了對應重載聲明。
適用版本:當前版本;聲明庫 legacy-script-engine-api JavaScript@v2.17.0 及以上
在 LSE 中用 block.setNbt 改了方塊狀態 NBT 後,服務端 NBT 已經變了,客戶端看到的方塊狀態卻不刷新(重進服務器才生效)。怎樣讓客戶端立即刷新?
最簡單的辦法:先把該位置設為空氣(mc.setBlock(pos, "minecraft:air")),再用帶新 NBT 的方塊 mc.setBlock 放一次,客戶端就會刷新。
也可以自己發包:BlockActorData 包(0x38)用於更新方塊實體 NBT,用 BinaryStream 依次 writeVarInt(x)、writeUnsignedVarInt(y)、writeVarInt(z)、writeCompoundTag(nbt),再 bs.createPacket(0x38),然後 player.sendPacket(pkt)。UpdateBlock 包(0x15)需要方塊的 runtimeId,取起來比較麻煩。只刷新區塊沒用。
當前版本仍提供 setNbt / BinaryStream 相關 API。
適用版本:LeviLamina + LSE 當前版本。未能從源碼或文檔中直接證實,僅供參考。
LSE 有沒有 API 可以讓某塊區域重新執行地形生成?
LSE 本身沒有。可以用第三方前置 GMLib 提供的刪除區塊 API,刪除後區塊會重新生成。注意結構(如村莊等)需要刪除結構起始點所在區塊才會重新生成。
適用版本:當前版本;需 GMLib。未能從源碼或文檔中直接證實,僅供參考。
LSE 的 JS 插件如何解析/使用 .mcstructure 結構文件(把玩家保存的結構文件傳到服務端使用)?
不需要外部庫,純 LSE 就能做:.mcstructure 本質是小端二進制 NBT。用 File.readFrom(path, true) 以二進制讀取得到 ByteBuffer,用 NBT.parseBinaryNBT(buf) 轉換為 NbtCompound,再調用 mc.setStructure(nbt, pos[, mirror, rotation]) 放置結構(反向可用 mc.getStructure 導出)。文件格式說明見 https://wiki.bedrock.dev/nbt/mcstructure#file-format。
適用版本:LSE 0.19.1 及以上(File.readFrom 二進制讀取)
LSE 的 mc.setBlock 傳入方塊類型字符串時,是否必須帶 minecraft: 前綴?
不一定。mc.setBlock 傳字符串時會用 Block::tryGetFromRegistry 按名字到原版方塊註冊表(BlockTypeRegistry::lookupByName)裡查找,查不到則直接返回 false;是否接受省略命名空間的寫法取決於 Mojang 的實現。有用戶反饋不加前綴(如 diamond_ore)一般也能放置成功,但文檔中的標準類型名帶前綴,建議寫成 minecraft:diamond_ore 以保證兼容。
適用版本:當前版本(行為取決於 BDS 原版註冊表)。未能從源碼或文檔中直接證實,僅供參考。
LSE 的連鎖採集插件可以在 iLand 領地內無權限挖掉方塊,如何在 JS 插件中判斷方塊是否在 iLand 領地中?
原因是插件用 Block.destroy() 直接破壞方塊,不會觸發領地保護所監聽的玩家破壞事件。可通過 LSE 的跨插件調用導入 iLand 導出的函數判斷:
const posGetLand = ll.imports("ILAPI_PosGetLand"); // 旧写法 ll.import 仍是 ll.imports 的别名
if (posGetLand(targetBlock.pos) == -1) { /* 该位置不是领地 */ }也可以藉助第三方 LRCA 提供的 Block.playerWillDestroy 等接口模擬玩家破壞以觸發相關事件。
適用版本:當前版本;需安裝 iLand。未能從源碼或文檔中直接證實,僅供參考。
LSE 能否通過方塊狀態(block states)而不是 tileData 來設置方塊?還是隻能用 setblock 命令?
可以通過 NBT 設置方塊。方塊 NBT 包含 name 和 states 字段(SNBT 形如 {"name":"minecraft:xxx","states":{...}}),可先對任意方塊調用 block.getNbt().toSNBT() 查看結構,再構造對應的 NbtCompound(例如 NBT.parseSNBT(...))傳給 mc.setBlock(pos, nbt) 設置。
LSE 腳本中 mc.getBlock(pos).isAir 經常報錯(例如玩家傳送/進服時),怎麼修?
mc.getBlock 在維度不存在、高度越界或區塊未加載時會返回 null,需先判空再訪問屬性,例如:
let block = mc.getBlock(packetPos.add(0, 1, 0));
if (block && block.isAir) break;或使用可選鏈:mc.getBlock(...)?.isAir。
在 LSE JS 插件中構造座標時,和 C++ 的 Vec3 寫法一樣只傳 x,y,z 就行嗎?為什麼設置方塊沒有效果?
不行。C++ 的 Vec3 沒有維度,但 LSE 的 IntPos/FloatPos 必須帶維度 ID,需寫成 new IntPos(x, y, z, dimid)(0 主世界、1 下界、2 末地),否則座標不完整,用它調用 mc.setBlock 等操作會出問題。
在 LSE JS 插件裡,如何讓指定方塊被破壞時不產生掉落物?
可以攔截破壞事件後用方塊對象的 destroy 方法手動破壞方塊,並傳入 false 表示不生成掉落物:bl.destroy(false)。參數 drop 表示是否生成掉落物,返回是否成功破壞。
如何獲取存檔名稱?LSE(JS)有相關 API 嗎?
LSE 沒有直接提供獲取存檔名稱的 API。JS 中可以讀取 server.properties 獲取 level-name:
let levelname = /level-name=(.*)/.exec(File.readFrom('./server.properties'))[1];但注意這得到的是 worlds 下的存檔文件夾名(路徑),與存檔內部顯示的名稱不一定相同;做備份等需要路徑的場景用它就夠了。C++ 原生 mod 可以通過 Level 的 LevelData 獲取存檔名。