LegacyScriptEngine API:實體
LSE 中 pl.hurt(damage[,type[,source]]) 想讓傷害來源是另一個玩家,Player 對象能直接傳嗎?Player 和 Entity 對象有什麼區別,怎麼把 Player 轉成 Entity?
LSE 的 Player 對象(運行時類名 LLSE_Player)包含了 Entity 的大部分方法和屬性,但它與 Entity 是不同的類型。需要 Entity 參數的接口可以用 pl.toEntity() 把玩家轉換為實體對象(轉換失敗返回 null),toEntity 是早已存在的 API。
當前版本中 pl.hurt / en.hurt 的 source 參數內部同時接受 Entity 和 Player 對象,因此可以直接 target.hurt(damage, ActorDamageCause.EntityAttack, attackerPlayer);也可以傳 attackerPlayer.toEntity()。若需要走原版傷害計算(盔甲減免等),也可以用命令實現:
mc.runcmdEx(`execute as "<攻击者>" run damage <目标> <数值> entity_attack entity @s`)適用版本:LSE 0.23.x
LSE 中 entity.hurt() 需要傳整數傷害類型,如何得到枚舉值?onMobHurt 事件的 cause 能直接傳給 hurt() 嗎?
LSE 註冊了全局傷害原因枚舉對象 DamageCause(為兼容同時保留同內容的 ActorDamageCause),鍵為枚舉名、值為 int,可直接使用,例如 pl.hurt(1.0, ActorDamageCause.Fire) 或 pl.hurt(1.0, DamageCause.Fire);hurt 的簽名為 hurt(damage, type?, source?)。onMobHurt 回調的 cause 參數就是該枚舉的整數值,可直接傳給 hurt()。枚舉定義以 LeviLamina 源碼 src/mc/deps/shared_types/legacy/actor/ActorDamageCause.h 為準(文檔中的枚舉表可能不完整)。
適用版本:當前 LSE 版本
LSE 中 entity.name/getName 獲取 Addon 生物名稱時拿到的是未翻譯的鍵名(資源包 zh_CN.lang 裡明明有翻譯),如何把實體名翻譯成指定語言?
原因是 BDS 自 1.19.80 起改了加載順序,服務端 I18n 先於資源包加載,因此服務端只加載了原版(vanilla)語言文件,Addon 資源包裡的語言文件不會進入服務端 I18n。可選做法:
- 對原版實體,取實體
type(如minecraft:zombie),去掉"minecraft:"前綴拼成語言鍵entity.<名字>.name(如entity.zombie.name)再翻譯; - 安裝第三方 GMLIB,其內置的 I18nFix 修正加載順序(默認不啟用,需由 C++ 接口或依賴它的插件開啟),或用 GMLIB-LRCA 提供的接口把資源包的
zh_CN.lang手動加載進服務端 I18n,之後entity.name這類走服務端翻譯的接口即可直接返回中文; - 自己解析資源包
.lang文件做映射,或用 LSE 自帶的i18n.load加載插件自己的翻譯文件再用i18n.tr/trl翻譯(注意這是插件自身的翻譯系統,不是 BDS 的 I18n)。
適用版本:BDS 1.19.80 及以後;GMLIB 相關為第三方插件。未能從源碼或文檔中直接證實,僅供參考。
LSE JS 插件中把實體對象作為 Map 鍵或用 == 比較兩個實體對象,找不到/不相等怎麼辦?
LSE 每次返回的實體/玩家對象都是新創建的 JS 包裝對象,沒有自定義相等比較邏輯,直接用 ==/=== 或作為 Map 鍵比較不會相等。應使用實體的 uniqueId 作為鍵或比較依據,例如 Boss.find(entity => entity.uniqueId == mob.uniqueId)。
LSE 中 entity.distanceTo() 接受哪些參數?傳入 pos.x/pos.y/pos.z 報參數類型錯誤/too few arguments 怎麼辦?
distanceTo 傳 1 個參數時接受 IntPos、FloatPos、Player、Entity(直接傳 player.pos 這類座標對象即可,不需要拆成 .x .y .z);否則必須傳 4 個數字參數:x, y, z, dimid(只傳 3 個會報參數數量錯誤)。例如:
const pos = player.pos;
if (entity.distanceTo(pos) > R) { /* ... */ }若目標與實體不在同一維度,返回值為一個極大數(INT_MAX)。Player 也有同名的 distanceTo,另有別名 distanceToPos。
LSE 中判斷實體是否玩家,寫 entity.isPlayer 不加括號為什麼總是成立?
isPlayer 是函數,要寫 entity.isPlayer()(和 pl.isOP() 一樣加括號)。不加括號判斷的是函數對象本身,函數存在就恆為真。
LSE 中如何把實體對象(Entity)轉換為玩家對象(Player)?
使用 en.toPlayer();若該實體不是玩家或轉換失敗則返回 null,可先用 en.isPlayer() 判斷。該 API 在文檔“實體對象(Entity)”頁面中,也可在 legacy-script-engine-api 倉庫的 d.ts 類型定義(GameAPI/Entity/Entity.d.ts)裡查到。反方向可用 pl.toEntity()。
在 LSE 中怎樣做到玩家右鍵(交互)或左鍵(攻擊)某個實體時打開菜單?
右鍵交互用 LSE 0.9.5 起新增的 onPlayerInteractEntity 事件:
mc.listen("onPlayerInteractEntity", (pl, en, pos) => {
if (en.type == "minecraft:实体id") {
pl.runcmd("打开菜单的指令");
}
});交互指鼠標右鍵、觸屏長按實體或點擊交互按鈕。
左鍵攻擊可以用 onAttackEntity(player, entity),也可以用 onMobHurt:
mc.listen("onMobHurt", (m, s, d, c) => {
if (s && s.isPlayer() && m.type == "minecraft:实体id") {
s.toPlayer().runcmd("打开菜单的指令");
}
});注意 onMobHurt 的 source 可能為 null,要先判空。
適用版本:LSE 0.9.5 及以上
LSE 的 JS 插件 API 有生成或操作經驗球的接口嗎?
沒有經驗球專用接口,但可用通用的實體生成接口:mc.summonMob("minecraft:xp_orb", pos)(與 /summon 走同一路徑,0.19.1 起可用)生成並返回 Entity 對象,之後用實體 API 操作;也可以用 mc.runcmdEx("summon xp_orb x y z")。相關文檔見實體 API 頁面:https://levimc.org/zh-Hant/LegacyScriptEngine/apis/GameAPI/Entity/。
適用版本:LSE 0.19.1 及以上(summonMob)
LSE 腳本中如何為某個生物生成一份戰利品(掉落物)?
LSE 沒有直接的戰利品表 API,可選方式:
- 用
mc.spawnMob(type, pos)生成同類實體,再用entity.hurt(damage[, type[, source]])殺死使其掉落; - 使用原版
/loot命令(mc.runcmd),來源可指定實體(kill)或戰利品表(loot),可配合mainhand等模擬用工具(如搶奪)擊殺; - 自行讀取戰利品表 json 計算;
- 用 C++ 模組實現並導出給腳本。
未能從源碼或文檔中直接證實,僅供參考。
LSE 裡如何給玩家施加一個衝量/速度(類似 ScriptAPI 的 applyImpulse)?
使用 Entity 的 setPosDelta:player.toEntity().setPosDelta(x, y, z),也可以傳入 FloatPos,即 en.setPosDelta(delta)。它設置實體每刻的座標變化量(運動量),對玩家同樣有效,返回是否設置成功。
在 LSE 中監聽生物生成事件並在回調裡調用 mc.spawnMob 生成實體,結果陷入死循環/堆棧溢出導致崩服,為什麼?如何避免?
mc.spawnMob 底層調用的是 Level 的 Spawner(BedrockSpawner)的 spawnMob,與自然生成同一條邏輯,而生物生成事件(onMobTrySpawn,舊名 onMobSpawn)正是 hook 這個函數,所以在回調裡再 spawnMob 會再次觸發事件,無限遞歸。
解決辦法:
- 用一個標誌變量防重入:事件觸發時若標誌為
true就直接返回,否則置為true、生成實體、再置回false。 - 或改用 LSE 0.19.1 新增的
mc.summonMob(走 summon 命令的生成邏輯,不經過Spawner::spawnMob,但生成的實體會被設為持久化、不會自然消失,大量使用要注意)。
另外生成事件觸發時實體尚未生成,靠事後加 tag 判斷無效。若只是想增加生成數量,更推薦用行為包修改 spawn_rules 的 herd 大小。
適用版本:LeviLamina + LegacyScriptEngine 當前版本(mc.summonMob 需 LegacyScriptEngine 0.19.1 及以上)
想用 LSE 禁用絕大部分實體生成(包括刷怪蛋、命令等),LSE 能做到嗎?
LSE 能攔截的是走 Spawner::spawnMob 的生物生成:
onMobTrySpawn:return false攔截。文檔描述為“實體嘗試自然生成”,但其底層 hook 的是BedrockSpawner::spawnMob,非自然途徑如 LSE 自身的mc.spawnMob也會觸發;刷怪蛋等其他途徑是否經過此函數需自行測試。onMobSpawned:生成完成通知,不可攔截。- 投射物可用
onSpawnProjectile。
/summon 不走 spawnMob(其生成邏輯位於匿名命名空間函數 CommandUtilsAnon::_spawnEntityAt),需要原生 C++ hook 才能攔截。直接刪除實體註冊理論可行,但侵入性太強,可能引起插件衝突等問題,不推薦。
適用版本:LegacyScriptEngine 當前版本
想給實體綁定自定義數據(像物品那樣存自定義 NBT),以及在 LSE 中根據 uniqueId 獲取單個實體,怎麼做?
可以獲取實體的 uniqueId,把數據存到插件自己的數據文件裡;也可以用 en.addTag(tag) 給實體加標籤(C++ 中為 Actor::addTag)。按 uniqueId 獲取單個實體:LSE 0.9.5 起提供 mc.getEntity(id),參數為實體的 UniqueId 或 RuntimeId,獲取失敗返回 null;也可以用 mc.getAllEntities() / mc.getEntities(...) 遍歷查找。
適用版本:LegacyScriptEngine 0.9.5 及以上
想讓某個生物只對特定玩家可見、並且只攻擊該玩家,用 LSE JS 插件能實現嗎?
“只對特定玩家可見”可以通過攔截/定製發給客戶端的數據包實現(需藉助數據包相關的原生能力或插件);但判斷或控制生物鎖定的攻擊目標 JS 做不到,LSE 早已徹底移除 NativeAPI,需要用 C++ 原生 mod 實現。
適用版本:LegacyScriptEngine 0.8.19 及以上
能否用 LSE 獲取全部實體來清理未加載區塊裡的實體?C++ 中怎麼獲取全部實體?
不行。LSE 中獲取全部實體應使用 mc.getAllEntities()(mc.getEntities(pos...) 是按座標範圍查詢),兩者都只能拿到已加載的實體,拿不到未加載區塊中的實體,所以腳本寫不了未加載實體清理。C++ mod 中可以用 Level::getRuntimeActorList() 或 Level::getEntities() 獲取(同樣僅限已加載的)全部實體。
適用版本:LSE / LeviLamina 當前版本