LegacyScriptEngine API:玩家
LSE 中 Player 對象的 player.name 和 player.realName 有什麼區別?該用哪個?
player.realName 是玩家的真實名字(取自登錄身份中的 Xbox Live 名稱,不受插件改名影響);player.name 是玩家對象當前的名字字段,可能被插件/接口(如改名相關 API)修改。做身份識別或顯示真實玩家名時用 realName;但如果要作為存儲玩家數據的鍵,更推薦使用 player.uuid(玩家在 Xbox 改名後 realName 也會變)。
適用版本:當前所有 LSE 版本
LSE 中玩家下線後,之前保存的 Player 對象還能調用嗎?插件拋出的異常會讓服務器退出嗎?
不能依賴舊對象。LSE 的 Player 對象內部只持有玩家實體的弱引用,玩家下線後實體被銷燬,舊對象的屬性/方法會取不到玩家而返回 null/undefined(玩家重進後是新實體,舊對象也不會恢復)。正確做法是保存 uuid/xuid,需要時再用 mc.getPlayer(...) 重新獲取,並在定時任務等場景中先判斷是否為 null 再操作。插件回調中未捕獲的異常會被 LSE 捕獲並打印錯誤日誌,不會導致服務器退出。
適用版本:當前 LSE 版本
LSE 腳本插件如何給玩家播放聲音?
LSE 沒有專門的播放聲音 API。兩種做法:
- 執行原版
playsound命令,例如mc.runcmd(`playsound random.levelup "${pl.realName}"`)或mc.runcmdEx(...); - 自己用
BinaryStream構造PlaySoundPacket並createPacket後用pl.sendPacket(packet)發送,可參考 NBSPlayer 的實現:https://github.com/lgc-LLDev/NBSPlayer/blob/master/src/player.ts#L52-L73。
能用命令解決的話命令更簡單,發包更靈活(不刷命令輸出),兩種方式都可行。
適用版本:LeviLamina 上的 LegacyScriptEngine 當前所有版本
LSE 中傳送/構造座標時的維度參數填什麼?文檔寫的 [dimid] 是要傳數組嗎?
文檔中的方括號表示可選參數,不是數組,維度 ID 直接填數字:0 = 主世界,1 = 下界,2 = 末地。IntPos/FloatPos 由 x、y、z、dimid 組成,如 new IntPos(0, 64, 0, 0) / new FloatPos(0.5, 64, 0.5, 0),然後用 pl.teleport(pos) 或 pl.teleport(x, y, z, dimid) 傳送。
適用版本:當前所有 LSE 版本
LSE 中如何讓玩家在生存模式下飛行?用 pl.getNbt() 改 abilities.mayfly 再 pl.setNbt() 寫回為什麼不生效?
直接改玩家 NBT 的 abilities 不會生效。請使用 Player 的 setAbility 接口:pl.setAbility(AbilityID, value),AbilityID 為 Integer,value 為 Boolean 表示是否開啟;允許飛行(mayfly)對應的 ID 為 10(AbilitiesIndex::MayFly),例如 pl.setAbility(10, true)。調用後會同步能力數據給客戶端,立即生效。
適用版本:當前所有 LSE 版本
LSE JS 插件裡調用 player.sendToast 報參數錯誤或沒效果,且字符串裡的 ${变量} 沒有被替換,怎麼寫?
sendToast 必須同時傳兩個字符串參數:標題和內容,即 player.sendToast(title, message),少傳會報參數錯誤。另外 JS 中只有反引號 ` 包起来的模板字符串才会解析 ${},用单/双引号时 ${} 会被当作普通文本,应写成例如 player.sendToast("提示", `歡迎 ${player.realName}`)。
適用版本:LegacyScriptEngine 當前所有版本
LSE JS 插件中如何給所有在線玩家定時刷新側邊欄?
側邊欄是 Player 對象的方法(player.setSidebar),不是全局方法,要給所有人設置就需遍歷在線玩家;內容需定時刷新。不必放在 onTick 裡,用 setInterval 即可,例如:
setInterval(() => {
for (const player of mc.getOnlinePlayers()) {
player.setSidebar(title, data);
}
}, 毫秒);也可用 mc.getOnlinePlayers().forEach(...)。另建議在玩家進服時初始化一次。
適用版本:LegacyScriptEngine 當前所有版本(原為 LLSE)
LSE 插件中如何獲取某玩家周圍一定半徑內的玩家?用 execute 命令 + 正則解析輸出的方式經常報錯。
儘量不要用命令實現,直接遍歷在線玩家按距離過濾:
let plnames = mc.getOnlinePlayers().filter(player => player.distanceTo(pl) < R).map(player => player.realName);其中 pl 為中心玩家,R 為半徑(方塊)。distanceTo 可接受 Entity/Player/IntPos/FloatPos;不在同一維度時返回整數最大值,因此會被自然過濾掉。如不想包含中心玩家本人,可再加 player.xuid !== pl.xuid 之類的判斷。
LSE JS 中想維護一個在線玩家列表,玩家退出後用 list.filter 刪除卻刪不掉,怎麼寫?
Array.prototype.filter 不會修改原數組,必須把結果重新賦值:
let list = [];
mc.listen("onJoin", player => { list.push(player.realName); });
mc.listen("onLeft", player => { list = list.filter(name => name !== player.realName); });也可以不自己維護,直接用 mc.getOnlinePlayers() 獲取當前在線玩家,例如在 onLeft 時寫入 JsonConfigFile:config.set("players", mc.getOnlinePlayers().map(p => p.realName).filter(n => n !== player.realName))(onLeft 觸發時離開的玩家可能仍在在線列表中,需要手動過濾掉)。
適用版本:當前版本(JS 引擎)
LSE JS 插件中如何獲取當前所有在線玩家的名字列表(例如存進 json)?
用 mc.getOnlinePlayers().map(player => player.realName) 得到在線玩家真實名字數組,再寫入 json(如 JsonConfigFile 的 set)。向數組添加元素用 push。
適用版本:當前版本(JS 引擎)
LSE JS 插件裡想把玩家座標用 pl.tell 發給玩家,直接傳 pl.pos 報錯/獲取不到座標,該怎麼寫?
pl.pos 返回的是座標對象(FloatPos),而 pl.tell 的第一個參數要求是字符串,直接傳對象會因參數類型檢查失敗而報錯。發送前用 pl.pos.toString() 轉成字符串(或用模板字符串 `${pl.pos}`),也可以自己拼接 pl.pos.x / pl.pos.y / pl.pos.z / pl.pos.dimid。
LSE 中 pl.addEffect() 如何給玩家添加無限時長的效果?
pl.addEffect(id, tick, level, showParticles) 的持續時間參數傳 -1,可得到無限時長效果(與原版 /effect ... infinite 相同)。此行為取決於 BDS 原版對 -1 時長的處理。
未能從源碼或文檔中直接證實,僅供參考。
LSE 中 pl.getScore() 在計分板項不存在時會報錯,有什麼處理辦法?
這是設計行為,文檔也寫明“使用前必須保證對應的計分項已經存在”,官方無意修改。可以自己封裝:先用 mc.getScoreObjective(name) 檢查計分項是否存在,不存在時用 mc.newScoreObjective(name, displayName) 創建或直接返回 0;或用 try/catch 包住 pl.getScore()。也可以改用第三方前置(如 GMLIB)提供的計分板接口。
LSE 中 pl.isOp() 報錯不存在,判斷玩家是否為 OP 的 API 是什麼?
LSE 的 API 名是 pl.isOP()(OP 全大寫),isOp 是錯誤寫法,JS 區分大小寫。
LSE 中 player.isSurvival 對冒險模式的玩家也返回 true,如何準確判斷玩家遊戲模式?
pl.isSurvival 直接調用 BDS 的 Actor::isSurvival(),其語義由原版決定,不宜用來區分生存/冒險。要精確判斷請用 pl.gameMode(數值,對應 GameType:0 生存、1 創造、2 冒險、6 旁觀),例如 if (pl.gameMode === 2) { /* 冒险 */ };也可以直接用 pl.isAdventure 判斷是否為冒險模式。
LSE 中 setBossBar 的顏色參數有哪些取值?
pl.setBossBar(uid, title, percent, colour) 的 colour 是整數,直接轉換為 BDS 的 BossBarColor 枚舉:0 粉色(Pink)、1 藍色(Blue)、2 紅色(Red)、3 綠色(Green)、4 黃色(Yellow)、5 紫色(Purple)、6 深紫色(RebeccaPurple)、7 白色(White)。例如 pl.setBossBar(1145141919, "Hello", 80, 2) 顯示紅色血條。
LSE 中如何可靠地獲取玩家召喚的假人或指定名字的玩家?mc.getPlayer(name) 有什麼坑?
mc.getPlayer(name) 對名字是不區分大小寫的前綴匹配:完全相等的名字優先,否則返回名字以該字符串開頭且最短的玩家,所以可能拿到別的玩家。獲取後應判斷返回對象的 name 是否與目標名字完全相等。更可靠的做法是保存並使用 UUID 或 XUID 查找(mc.getPlayer 也接受 UUID/XUID/UniqueId/RuntimeId)。給假人名稱加一個玩家無法使用的前綴/標記也可以防止衝突。
LSE 中想讓 Boss 血條(bossbar)持續刷新,寫成 setInterval(player.setBossBar(...), 500) 卻只執行一次或提示 player 未定義,正確寫法是什麼?
setInterval 的第一個參數必須是函數,寫成 setInterval(player.setBossBar(...)) 只會立即執行一次 setBossBar 並把返回值當參數。應傳匿名函數,並保存 setInterval 返回的 id,在 Boss 死亡時 clearInterval。
不要長期持有 player / entity 等 mc 對象,應保存 xuid,在定時器裡用 mc.getPlayer(xuid) 重新獲取並判空。示例:
let players = [];
mc.listen("onAttackEntity", (pl, en) => {
if (!en.hasTag("boss")) return;
if (!players.includes(pl.xuid)) players.push(pl.xuid);
});
const timer = setInterval(() => {
for (const xuid of players) {
const p = mc.getPlayer(xuid);
if (!p) continue;
p.setBossBar(bossId, "名称", Math.floor(boss.health / boss.maxHealth * 100), 2);
}
}, 500);Boss 死後 clearInterval(timer),並對玩家調用 removeBossBar(bossId)。setBossBar 參數為 (uid, title, percent 0~100, colour)。若要給附近所有玩家顯示,可遍歷 mc.getOnlinePlayers() 按距離篩選。
適用版本:LSE 當前所有版本
在 LSE 腳本中註冊玩家 PAPI(PlaceholderAPI)變量時,怎樣接收額外參數?文檔只有服務器 PAPI 的示例,回調參數裡只有玩家對象。
在註冊玩家變量的回調裡,玩家對象後面再加一個參數就能收到額外參數,回調寫成 (pl, param) => {...}。補全和類型聲明可能還沒跟上,以 PAPI 插件實際傳入的內容為準。不確定時可以先把 param 用 log 打出來看結構。
此功能依賴安裝了第三方 PlaceholderAPI 插件(提供 registerPlayerPlaceholder 的 LSE 綁定)。
適用版本:安裝了第三方 PlaceholderAPI 插件的環境。未能從源碼或文檔中直接證實,僅供參考。
在 LSE 中,玩家切換維度時怎樣判斷玩家已經加載完畢?
可以讀玩家對象的 pl.isLoading 屬性(表示玩家是否正在加載)。在 onChangeDim 事件裡用 setInterval / setTimeout 輪詢,直到它變成 false 再做後續操作。切換維度期間讀到的不少玩家屬性可能是 undefined,要做空值判斷。
注意從末地返回傳送門回到主世界時不會觸發 onChangeDim。
適用版本:LSE 0.23.x。未能從源碼或文檔中直接證實,僅供參考。
在 LSE 中用 pl.rename(newName) 改了玩家頭頂名字後,pl.name 拿到的仍然是真名。有沒有辦法獲取玩家頭頂顯示的名字(nametag)?
pl.rename 實際改的是玩家的 NameTag,而 pl.name / pl.realName 返回的是玩家原名,不會變。LSE 0.19.1 起新增了 en.getCustomName(),它返回實體的 NameTag,所以可以用 pl.toEntity().getCustomName() 拿到頭頂顯示的名字。
如果還要維護“真名到假名”的映射或做重名檢查,仍建議在調用 rename 時自己記錄 uid、真名、假名的對應關係(文件或數據庫),需要時用 data.getAllPlayerInfo() 拿到所有玩家信息再比對。
0.19.1 之前的版本只能自行記錄。
適用版本:LSE 0.19.1 及以上
在 LSE 中用 pl.setBossBar 給玩家設置 BossBar 時,要傳的 uid 應該填什麼?
BossBar 的原理是給該玩家發一個假實體(AddActor)再發 BossEvent 包,uid 就是這個假實體的 ID,隨便填一個不衝突的數字即可(負數也可以),同一個 uid 對應一行 BossBar,removeBossBar(uid) 時用同一個值。
不要填已存在實體的 uniqueId:LSE 不做判斷,會導致該實體在客戶端被假實體替換而消失。
適用版本:LSE 0.23.x
在 LSE 插件中怎樣向全服玩家發送廣播或通報消息?
可以用 mc.broadcast(msg[,type])(type 默認為 0 普通消息,1 為聊天,5 為物品欄上方的 Tip,9 為 JSON)。也可以遍歷在線玩家逐個發:mc.getOnlinePlayers().forEach(pl => pl.tell(msg))。還可以用 mc.runcmd(`say ...`) 或 tellraw 命令。
注意用 say 時消息會帶上 [服务器] 之類的前綴(隨 server.properties 的 language 變化)。
適用版本:LSE 0.23.x
LSE 插件中給玩家顯示標題、向全服廣播消息時,用執行 title / say 命令的方式合適嗎?
不建議用 mc.runcmd 執行 title / say 命令,LSE 有現成接口:給玩家顯示標題用 pl.setTitle(content[, type[, fadeInTime, stayTime, fadeOutTime]]),全服消息用 mc.broadcast(msg[, type])。有接口就優先用接口。
適用版本:LSE 當前所有版本(含 v0.23.1)
LSE 有沒有判斷玩家是否處於爬行 / 游泳狀態的 API?
有。player.isSwimming 和 player.isCrawling 屬性,LSE 0.19.1 起提供。
適用版本:LSE 0.19.1 及以上
LSE 的 TypeScript 類型定義裡,mc.getPlayer 拿到的玩家對象沒有模擬玩家(SimulatedPlayer)的方法,怎麼調用模擬玩家 API?
類型定義中 mc.getPlayer 返回 Player,而 SimulatedPlayer 繼承自 Player(declare class SimulatedPlayer extends Player)。運行時模擬玩家的 simulateXxx 方法本來就掛在玩家對象上,只是類型不匹配。可先用 player.isSimulatedPlayer() 判斷,確認後手動斷言 (player as SimulatedPlayer) 再調用;也可以用 // @ts-ignore 繞過類型檢查。通過 mc.spawnSimulatedPlayer 創建時返回的直接就是 SimulatedPlayer 類型。
適用版本:當前版本(使用 legacy-script-engine-api 類型定義的 LSE TS 插件)
LSE 腳本中 pl.xuid 返回空值是什麼原因?
檢查 server.properties 中的 online-mode:離線模式下玩家沒有經過 Xbox 驗證,沒有 XUID,pl.xuid 會為空字符串。另外若通過遠程調用(ll.exports / ll.imports)在插件間傳遞玩家,需確認傳入的確實是 Player 對象,而不是普通 object。
未能從源碼或文檔中直接證實,僅供參考。
LSE 腳本插件中玩家死亡復活後無法移動(手機端搖桿消失),控制台也沒有報錯,可能是什麼原因?
這類問題一般是插件自身邏輯錯誤,引擎不會報錯。常見原因有兩個:一是玩家死亡後插件仍在持續設置玩家血量(如 setHealth),導致玩家狀態異常;二是在 onMobHurt 事件回調裡又對玩家造成傷害(如 hurt),傷害會再次觸發 onMobHurt,形成無限遞歸或死循環。排查並修正這些邏輯即可,例如在回調中判斷玩家是否已死亡,避免在 onMobHurt 內直接再次造成傷害,或加重入標記。
適用版本:當前版本(屬於腳本邏輯問題)。未能從源碼或文檔中直接證實,僅供參考。
卸載了修改最大血量的模組/插件後,玩家最大血量仍不是默認值,怎麼在服務器後臺直接把某玩家最大血量改回 20?
在服務端控制台用 LSE 的腳本調試命令執行:
jsdebug mc.getPlayer('玩家名').setMaxHealth(20)即可把該玩家最大血量恢復為 20。注意調試命令隨後端不同:QuickJS 後端為 jsdebug,Lua 為 luadebug,Python 為 pydebug;Node.js 後端沒有調試命令。
適用版本:LeviLamina + LSE(對應腳本後端已安裝)
在 LSE 中讀取玩家背包等物品數據,玩家 NBT 裡有哪些相關的鍵?
這些鍵都在玩家 NBT 的根目錄下:Armor(盔甲欄)、Inventory(背包欄)、Offhand(副手欄)、PlayerUIItems(光標處與合成欄等 UI 物品)。在線玩家更推薦直接用 pl.getInventory()/pl.getArmor() 等容器接口;離線玩家可用 mc.getPlayerNbt(uuid) 讀取 NBT 後取這些鍵。
適用版本:LeviLamina + LegacyScriptEngine(鍵名取決於 BDS 原版存檔格式)。未能從源碼或文檔中直接證實,僅供參考。
如何修改玩家的飛行速度(LSE 插件)?
LSE 沒有直接設置飛行速度的 API(player.setAbility 只能設置布爾型能力)。可以通過 player.getNbt() 取得玩家 NBT,修改 abilities 下的 flySpeed 字段(默認 0.05f),再用 player.setNbt(nbt) 寫回。有用戶反饋,修改後可能需要玩家重新進入遊戲才會生效。
適用版本:LSE(LeviLamina)當前版本(flySpeed 字段屬於 BDS 原版玩家 NBT 結構)。未能從源碼或文檔中直接證實,僅供參考。
如何在服務器控制台快速查看某個在線玩家的 UUID(用於查找該玩家的數據文件)?
在控制台執行 LSE 的調試命令(QuickJS 引擎):jsdebug mc.getPlayer('玩家名字').uuid。注意玩家必須在線才能通過 mc.getPlayer 獲取。
適用版本:當前版本(需 QuickJS 引擎)
插件開發中有沒有獲取玩家在線時長/遊玩時長的 API?
LSE/LeviLamina 沒有直接提供遊玩時長 API,基岩版 BDS 本身也不存儲玩家的遊玩時長(玩家 NBT 裡的 Age 不是這個)。需要插件自己在玩家進服(onJoin)/退服(onLeft)時記錄時間並累計保存;或者直接安裝現成的在線時長插件。
未能從源碼或文檔中直接證實,僅供參考。
有沒有辦法讓基岩版服務器的最大玩家數動態變化:沒人時 maxplayers 為 1,每進一個人就加一?
用 LSE 的 JS 插件幾行就能實現:
setInterval(() => mc.setMaxPlayers(mc.getOnlinePlayers().length + 1), 1000);也可以使用現成第三方插件 DynamicPlayerLim(https://www.minebbs.com/resources/dynamicplayerlim-tps.5414/),除了讓上限=在線人數+1,還能在 TPS 過低時阻止玩家進入(原為 LL2 插件,兼容性需自行測試)。
適用版本:LegacyScriptEngine 當前版本
服務器裡如何隱藏玩家頭頂的遊戲 ID(名字),命令方塊能做到嗎?
命令方塊無法實現,只能用插件:最簡單的方法是把玩家重命名為空字符串(LSE 的 player.rename(""));或者攔截髮給客戶端的數據包,把顯示玩家名稱的屬性改為 false。
適用版本:LegacyScriptEngine 當前版本
服務器裡突然有玩家莫名其妙獲得 OP,如何快速查看 permissions.json 裡有哪些 OP 玩家、排查是否有插件後門?
可以在後臺用 LSE 的 jsdebug 執行下面的命令,把 permissions.json 中的 xuid 轉成玩家名輸出:
jsdebug JSON.parse(File.readFrom("permissions.json")).map(item => data.xuid2name(item.xuid)).join(", ")若列表正常,需要檢查插件是否有後門:LSE 插件執行設置權限等敏感操作(如 setPermLevel)時會被記錄到 logs/LegacyScriptEngine/Sensitive_Operation_Records-<后端>.log(如 JS 後端為 Sensitive_Operation_Records-Js.log,另有 Lua/NodeJs/Python),格式為 [操作]<插件名> 内容,可在其中查找相關記錄。
適用版本:LegacyScriptEngine 當前版本
能否在 LSE 中給玩家改名(不通過 Xbox 付費改名)?
可以使用玩家對象的 rename 方法:JS 中 pl.rename("Steve"),Lua 中 pl:rename("Steve"),返回是否成功(Boolean)。臨時改名可在控制台用 QuickJS 引擎的調試命令 /jsdebug 執行 mc.getPlayer("玩家原名").rename("新名字")(Node.js 引擎沒有調試命令)。這只是服務器內顯示名,不會修改玩家的 Xbox 賬號名。
適用版本:LSE 當前所有版本
升級到新版後,玩家無法破壞方塊、無法丟棄物品(但能打開箱子),是什麼原因?
原因是插件調用 pl.setAbility(AbilityID, value) 時使用的數字索引與當前 BDS 的 AbilitiesIndex 枚舉不一致(LSE 直接把數字轉換為 AbilitiesIndex),舊插件按舊索引設置,結果關掉了挖掘等能力。需按當前枚舉修改插件,當前映射為:Build=0、Mine=1、DoorsAndSwitches=2、OpenContainers=3、AttackPlayers=4、AttackMobs=5、OperatorCommands=6、Teleport=7、Invulnerable=8、Flying=9、MayFly=10、Instabuild=11、Lightning=12、FlySpeed=13、WalkSpeed=14、Muted=15、WorldBuilder=16、NoClip=17、PrivilegedBuilder=18、VerticalFlySpeed=19。BDS 更新可能再次改變枚舉。若能力已被寫入關不掉,可把玩家切到別的遊戲模式再切回生存來重置能力。