LegacyScriptEngine API:物品與容器
LSE 中 player.giveItem("minecraft:xxx", 数量) 不起作用,怎樣正確給玩家物品?想一次給超過一組怎麼辦?
giveItem 的第一個參數必須是物品對象(Item),不能直接傳命名空間 ID 字符串。先用 const item = mc.newItem("minecraft:snowball", 16) 創建物品對象,再 pl.giveItem(item)。
當前版本支持可選第二參數 amount:當 amount 大於該物品最大堆疊數時(如 pl.giveItem(item, 100)),會按最大堆疊數自動拆成多組給予,背包滿時多餘物品會被拋出(掉落);注意按當前實現,amount 不超過最大堆疊數時仍按物品自身的 Count 給予,此時應直接在 mc.newItem 時指定數量。
也可以用 mc.spawnItem(item, pos) 在指定位置生成掉落物,或用 mc.runcmdEx 執行 give 命令。
適用版本:當前 LSE 版本(amount 參數為較新版本加入)
LSE 插件如何判斷玩家是否空手?監聽 onAttackBlock 時玩家空手會導致報錯(物品參數為空)。
onAttackBlock 回調為 function(player, block, item),玩家空手時 item 傳入的是空值(undefined),使用前要先判空:if (!item) { /* 空手 */ }。也可以用 player.getHand() 獲取主手物品,它總是返回一個 Item 對象,空手時可用 it.isNull() 判斷(也可檢查其 type 是否為 minecraft:air)。
備選方法是用 mc.runcmdEx 配合 hasitem 選擇器,例如 tag @a[hasitem={item=air,location=slot.weapon.mainhand}] add xx,再檢測玩家的 tag,但一般不推薦用命令實現。
LSE 腳本里怎麼讀取物品的附魔等詳細信息?文檔裡找不到 getNbt,getData 一定要先 getNbt 嗎?
物品附魔等詳細信息需要通過 NBT 讀取。用 player.getHand() 拿到玩家手上的 Item 對象,然後調用 item.getNbt() 得到 NbtCompound。getData(key) 是 NbtCompound 類的方法,而 getNbt() 恰好返回這個類型,所以通常寫成先 getNbt 再 getData。
getNbt 寫在各個對象類(Item、Entity、Block、Player 等)的文檔頁裡,不在 NBT 頁,可在文檔中搜索 getNbt。NBT 中的 List 相當於 JSON 數組,Compound 相當於 JSON 對象。物品 NBT 結構可參考 zh.minecraft.wiki 的“基岩版世界格式”等頁面。
若要在商店之類的插件中完整保存物品(附魔、潛影盒內容等),可直接用 nbt.toSNBT() 把整個物品 NBT 存成 SNBT 字符串,需要時再用 NBT.parseSNBT() 還原並通過 mc.newItem(nbt) 或 it.setNbt(nbt) 使用。
LSE 中如何用 NBT 修改物品的 Lore 等顯示信息?直接給 NbtList 傳 JS 數組或寫 "1b" 這類值為什麼不生效?
Lore 標籤位於物品 NBT 的 tag.display 下。NbtList 需要用 new NbtList([new NbtString("文本")]) 構造,不能直接傳 JS 數組 [];修改後要 item.setNbt(nbt),再調用 player.refreshItems() 刷新。更簡單的方式是直接用 item.setLore([...]),或用 NBT.parseSNBT 構造 NBT。
字節類型字段(如 Unbreakable)應寫 new NbtByte(1),不要寫字符串 "1b" 或 true;附魔等級是 short。物品根 NBT 一般只有 Name、Count、Damage、WasPickedUp 等,其餘標籤(如附魔 ench、display)在 tag 裡。對已存在的鍵再 setTag 會直接覆蓋;JS 中 NBT 的 getData 返回的是值而不是引用。
在 LSE 中用 mc.newItem() 創建 addon 自定義物品失敗(參數確認無誤),是什麼原因?
插件加載時服務器還沒啟動完,世界和物品註冊表(包括 addon 自定義物品)還沒準備好。把創建物品的代碼放進 mc.listen("onServerStarted", () => { ... }) 回調裡執行即可。
新版 LSE 在這種情況下會直接拋異常(如 ll::service::getLevel() returns nullptr 或 Item not found),可據此判斷。
適用版本:LSE 0.23.x
LSE 插件中如何在玩家死亡的位置生成一個掉落物?
監聽玩家死亡事件 onPlayerDie(回調原型 function(player, source)),在回調中仍可讀取 player.pos,然後先用 mc.newItem("minecraft:xxx", 数量) 創建物品,再用 mc.spawnItem(item, pos) 在該位置生成掉落物。例如:
mc.listen("onPlayerDie", (pl, src) => {
const it = mc.newItem("minecraft:diamond", 1);
mc.spawnItem(it, pl.pos);
});適用版本:LSE 當前所有版本(含 v0.23.1)
LSE 插件中如何把玩家某個物品減少指定數量(例如 64 個草方塊減到 32 個)?
直接用 pl.clearItem(type, count),例如 pl.clearItem("minecraft:grass_block", 32),返回實際清除的數量。當前實現按格子逐個扣減,某格數量多於剩餘要清除的數量時只會扣掉需要的數量,不會整組刪除;物品 ID 要寫完整命名空間(minecraft:...)。
也可以用 mc.runcmdEx 執行原版命令 clear 玩家名 minecraft:grass_block 0 32,或者自己從物品欄取 Item 修改後調用 pl.refreshItems() 刷新客戶端顯示。
clearItem 的部分扣減問題在 0.9.3 中已修復。
適用版本:LSE 0.9.3 及以上
LSE 插件中如何獲取某物品在當前服務器中的最大堆疊數(addon 可能修改原版物品堆疊數或添加自定義物品),且不依賴 LegacyRemoteCall 等插件?
LSE 的物品對象已直接提供該屬性:用 mc.newItem(type, 1) 創建物品後讀取 it.maxStackSize(或 it.maxCount,0.16.1 加入),取到的是服務器物品註冊表中的實際值,包含 addon 的修改和自定義物品。當前版本同時有 maxStackSize。
舊版本沒有該屬性時,可用 mc.newItem(type, 一个很大的数) 創建後讀取 count 作為變通。
適用版本:LSE 0.16.1 及以上
LSE 插件在 onUseItem 事件裡對回調參數 item 做 item.count-- 或修改 NBT 後調用 player.refreshItems(),玩家手中物品數量都不變,如何讓玩家使用物品後手持物品數量減 1?
事件回調給出的物品對象是拷貝(底層 hook 的函數逐層 clone),修改它不會影響玩家背包;且 item.count 是隻讀屬性。應在回調中通過 player.getHand() 取玩家主手物品再修改:
mc.listen("onUseItem", player => {
const item = player.getHand();
if (item.count > 1) {
item.setCount(item.count - 1); // LSE 0.19.1+;旧版可改 NBT:nbt.setByte("Count", item.count - 1) 后 item.setNbt(nbt)
} else {
item.setNull();
}
player.refreshItems();
return false;
});NBT 對象不能像普通 JS 對象那樣直接 nbt.Count 讀寫,要用 getTag / setByte 等方法;若想像普通 object 一樣操作,可使用第三方 iListenAttentively 的 LSE 導出封裝(ila-lseexport,https://github.com/MiracleForest/iListenAttentively-LseExport)。
適用版本:LSE 當前所有版本;it.setCount 需 0.19.1 及以上
LSE 新增的修改玩家物品的 API,修改完之後需要手動刷新玩家背包嗎?
需要。修改物品後要再調用 player.refreshItems() 刷新玩家物品欄 / 盔甲欄,客戶端才會顯示更改。
LSE 有沒有容器(Container)相關的 API?文檔在哪?
有,文檔見 https://levimc.org/zh-Hant/LegacyScriptEngine/apis/GameAPI/Container/。但該 API 只能操作已有容器(如方塊容器、玩家物品欄),不支持主動給玩家打開一個容器界面;需要主動打開容器 UI 的需求建議用原生 C++ mod 或第三方前置實現。
LSE 能否給玩家手持物品(或插件生成的物品)添加自定義 NBT 標籤,之後讀取它來識別物品?BDS 會不會把不認識的 NBT 刪掉?
可以,物品支持自定義 NBT 標籤(“BDS 會去掉不認識的 NBT”並非指這種情況)。做法:
const it = player.getHand();
const nbt = it.getNbt();
// 在 nbt 中写入自定义 tag 后
it.setNbt(nbt);
player.refreshItems(); // 同步给客户端之後讀取 getNbt() 中的該 tag 來識別物品。
LSE 腳本中如何判斷玩家背包是否已滿(或是否還有空位放入某物品)?
推薦用 player.getInventory().hasRoomFor(item) 判斷容器能否放下該物品。也可以遍歷:
const hasEmpty = (pl) => pl.getInventory().getAllItems().some(it => it.isNull());找到空物品欄即表示未滿。另外容器還有 addItemToFirstEmptySlot / addItem 方法可直接放入。
LSE(JS 插件)能否讀取/修改玩家的物品欄,包括 UI 槽位(如工作臺中的物品)?
可以通過玩家 NBT 實現:用 pl.getNbt() 讀取整個玩家 NBT(其中包含背包、UI 槽位物品等),修改後再用 pl.setNbt(nbt) 寫回。查包類插件(如 Invsee)就是複製整個玩家 NBT 實現的。
在 LSE 中修改物品 NBT 時把整個 tag 重新設置,導致物品原有附魔丟失(甚至崩服),如何在修改時保留附魔?
不要新建整個 tag 覆蓋原有 NBT。應先用 item.getNbt() 取出原 NBT,在其上修改需要的字段後再 item.setNbt(nbt)。沒有從普通 JS Object 直接生成 NBT 的函數,手工用構造函數拼接容易出錯;更方便的做法是用 nbt.toSNBT() 得到文本,修改後用 NBT.parseSNBT(snbt) 解析回 NBT 再寫回。
在 LSE 腳本里修改物品 NBT 添加自定義附魔,不管寫什麼附魔 id 和等級,結果都顯示為“保護 0”,為什麼?
NBT 類型寫錯了。物品 tag 中附魔列表 ench 裡的 id 和 lvl 是 Short 類型(SNBT 中如 17s 的 s 後綴表示 short),不是字符串或 int;在 LSE 中用 new NbtShort(值) 構造即可。C++ mod 中可直接用 EnchantUtils::applyEnchant 添加附魔。另外 NBT 中沒有 bool 類型,b 後綴表示 byte。
適用版本:LSE / LeviLamina 當前版本(附魔 NBT 結構為 BDS 原版行為)
在 LSE(LLSE JS)插件中如何獲取物品的 NBT 字符串,以及如何把 SNBT 轉回 NBT 來生成物品?
用 物品对象.getNbt().toSNBT() 獲取 SNBT 字符串;用 NBT.parseSNBT(snbt) 把 SNBT 轉為 NbtCompound 對象,再用 mc.newItem(nbt) 創建物品。
LSE 插件能否自定義合成配方?
LSE 本身沒有註冊合成配方的 API。可以調用第三方前置 GMLIB 提供的配方接口(文檔:https://groupmountain.github.io/Documentation/lse/api/Recipes/),或者通過行為包(服務端配方 JSON 文件)直接添加配方。
適用版本:LSE 當前所有版本