跳到正文
本頁目錄

LegacyScriptEngine API:事件

LSE 能註銷(取消監聽)通過 mc.listen 註冊的事件監聽器嗎?怎麼實現取消監聽?

LSE 的腳本 API 沒有註銷監聽的接口:mc.listen(event, callback) 只返回一個表示是否註冊成功的 Boolean,不返回可以用來移除的句柄。插件被卸載或重載時,LSE 會自動清除該插件註冊的全部事件監聽器。

如果需要在運行時取消監聽,可以在腳本里自己包裝一層:對每個事件只調用一次 mc.listen,回調裡把事件分發給自己維護的處理函數列表,需要取消時從列表中刪掉對應的處理函數即可。

(LeviLamina 的 C++ EventBus 提供 removeListener,C++ mod 可以直接移除監聽器。)

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

LSE 中 onAttackEntity 事件的回調還提供 damage(傷害值)參數嗎?

不提供。LSE 的 onAttackEntity 回調原型為 function(player, entity),LL2 時代的 damage 參數已刪除,請以 LSE 文檔為準;回調返回 false 可攔截攻擊。

適用版本:LSE 所有版本(LeviLamina 時代)

LSE 中用 onUseItem 實現“手持物品右鍵打開菜單/釋放技能”,為什麼 PC(Win10)端右鍵一次會觸發很多次?該監聽哪個事件?

對空氣使用物品應監聽 onUseItem(對方塊使用才是 onUseItemOn)。PC 端按住/點擊右鍵時 onUseItem 會連續觸發多次,需要自己做防抖/冷卻:按玩家記錄上次觸發時間(如 Map<xuid, timestamp>),短時間內(如 200~500ms)的重複觸發直接忽略,可參考 CMenu 等菜單插件的實現。移動端右鍵對應長按。也可以配合 onAttackEntity(左鍵攻擊實體)等事件組合實現技能。

適用版本:LSE 當前版本

LSE 中如何禁止活塞推動指定方塊(如箱子、漏斗),防止領地外活塞把方塊推進/推出領地?

監聽 onPistonTryPush 事件,回調 function(pistonPos, block) 返回 false 即可攔截。例如:

js
mc.listen('onPistonTryPush', (pistonPos, block) =>
  ["minecraft:chest", "minecraft:hopper"].includes(block.type) ? false : true);

領地插件可用 block.pos 判斷被推方塊是否在領地內。早期 LSE 曾有該事件回調中方塊座標錯誤(都是活塞自身座標)導致領地插件失效的 bug(issue #137),已在 LSE 0.7.12 修復。注意活塞被阻擋無法推動時該事件會循環觸發。

適用版本:LSE 0.7.12 及以上

LSE 腳本插件如何實現耕地防踩?onFarmLandDecay 事件還能用嗎?

可以。監聽 "onFarmLandDecay"(耕地退化)事件,回調原型 function(pos, entity):pos 為退化耕地的座標(IntPos),entity 為造成退化的實體(Entity)。回調返回 false 即可攔截,耕地不會變回泥土。例:

js
mc.listen("onFarmLandDecay", (pos, entity) => false);

注意該事件可能會被多次觸發,回調裡不要做開銷大的操作;如只想保護特定區域/特定實體,可根據 pos、entity 自行判斷。

適用版本:LegacyScriptEngine 0.23.x;舊 LiteLoaderBDS 2.x LLSE 同樣適用

LSE 中 mc.listen 的回調參數是按名字還是按順序傳入的?例如 mc.listen("onCmdBlockExecute",(pos,cmd)=>{log(cmd)}) 輸出的卻是指令而不是座標。

按順序傳入。監聽事件相當於 LSE 調用你插件裡的函數,LSE 只按文檔中該事件監聽函數原型的固定參數順序傳參,不會理會你起的變量名。onCmdBlockExecute 的原型是 function(cmd, pos, isMinecart),所以第一個參數是指令字符串、第二個是座標(FloatPos)、第三個表示是否為命令方塊礦車。變量名可以隨意,但建議按文檔原型命名:

js
mc.listen("onCmdBlockExecute", (cmd, pos, isMinecart) => { log(cmd, pos); })

LSE 中 onBlockExploded 事件是否包含凋靈破壞方塊(onWitherBossDestroy)?

不包括。凋靈本體破壞方塊是單獨的事件,需要監聽 onWitherBossDestroy(原型 function(witherBoss, AAbb, aaBB),可攔截);onBlockExploded(原型 function(block, source))只針對爆炸破壞的方塊。

未能從源碼或文檔中直接證實,僅供參考。

LSE 中 onDestroyBlock 無法監聽挖掘基岩等不可破壞方塊,如何監聽玩家對這類方塊的挖掘/攻擊?

onDestroyBlock(玩家破壞方塊完成)只在方塊真正被破壞時觸發,基岩、末地門框架等不可破壞方塊不會觸發。要監聽玩家對這類方塊的敲擊,可使用 onAttackBlock(原型 function(player, block, item))或 onStartDestroyBlock(原型 function(player, block)),兩者在當前版本都基於玩家攻擊方塊事件,返回 false 可攔截;在回調裡自行實現“可破壞”邏輯(例如 mc.setBlock 設為空氣並掉落物品)。

如果遇到事件不觸發的問題,請在 GitHub issue 中附上可復現的文字代碼。

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

LSE 中 onPlayerDie 事件如何判斷傷害來源是否為玩家,並給擊殺者在計分板上加分?

onPlayerDie 的原型是 function(player, source),source 是傷害來源實體(Entity,可能為 null)。先判斷 source 存在且是玩家,再用 toPlayer() 轉為 Player 對象後操作計分板;Entity 對象沒有 addScore 等計分板方法。示例:

js
mc.listen("onPlayerDie", (pl, src) => { if (src && src.isPlayer()) { src.toPlayer().addScore("kills", 1); } });

計分項需事先存在。

LSE 中事件回調(如 onPreJoin)能否異步執行?在事件裡執行異步代碼有問題怎麼處理?

事件回調由 LSE 同步調用,只有回調同步返回的 false 才會攔截事件。回調裡可以用 Promise/then 或把回調寫成 async 函數來做異步工作(Node.js 後端每 tick 會驅動事件循環和微任務),但 async 函數返回的是 Promise 而不是 false,await 之後再 return false 也無法攔截——需要攔截的判斷必須在同步部分完成。

onPreJoin 中需要給玩家附加數據時,也可以自己用一個按玩家名/xuid 索引的對象存儲,不一定要用 setExtraData。

LSE 中如何攔截事件?為什麼用 mc.listen("onPlayerPullFishingHook", (player,entity,item) => { fishingHookEvent(player,entity,item) }) 並在 fishingHookEvent 裡 return false 攔截不生效?

LSE 事件回調返回 false 即攔截事件(並非所有事件都支持攔截,以文檔中標註“攔截事件:函數返回false”為準;onPlayerPullFishingHook 支持攔截)。上面的寫法外層箭頭函數用了大括號卻沒有 return,內層函數的返回值沒有傳出去。應寫成:

js
mc.listen("onPlayerPullFishingHook", (player,entity,item) => { return fishingHookEvent(player,entity,item); });

或直接:

js
mc.listen("onPlayerPullFishingHook", (player,entity,item) => false);

LSE 中如何攔截凋靈生成時的大爆炸?onBlockExploded / 爆炸事件 return false 攔截不了。

onBlockExploded(方塊被爆炸破壞)只是方塊被炸燬時的通知,文檔標註“不可以攔截”,return false 無效。要攔截爆炸本身應監聽 onEntityExplode(由實體引起的爆炸,凋靈生成爆炸的來源是凋靈實體)或 onBlockExplode(由方塊引起的爆炸)並返回 false。

LSE 0.21.2 起這兩個事件改由 iListenAttentively 提供,底層 hook 的是 Explosion::explode,所有爆炸都會經過並可取消。如需更細粒度控制,也可在原生(C++)插件中直接使用 iListenAttentively 的 ila::mc::ExplosionBeforeEvent。

適用版本:LSE 0.21.2 及以上(依賴 iListenAttentively)

LSE 中對玩家調用 player.kick() 會觸發 onLeft 事件嗎?

會。player.kick() / disconnect() 內部調用 Player::disconnect 斷開連接,而 onLeft 基於 LeviLamina 的 PlayerDisconnectEvent(hook ServerPlayer::disconnect),因此 kick 玩家也會觸發一次 onLeft。若在 onLeft 中清理玩家臨時數據需注意這一點(服務器關閉過程中不會觸發 onLeft)。

適用版本:LSE 當前版本

LSE 插件中如何實現玩家對黑曜石使用物品(如桶)時把黑曜石變成岩漿?

監聽 onUseItemOn 事件(回調 function(player, item, block, side, pos)),判斷方塊類型後用 mc.setBlock 替換:

js
mc.listen('onUseItemOn', (player, item, block) => {
  if (block.type === 'minecraft:obsidian' && item.type === 'minecraft:bucket') {
    mc.setBlock(block.pos, 'minecraft:lava', 0);
  }
});

可按需去掉對手持物品(桶)的判斷。注意:Win10 客戶端右鍵可能在服務端連續多次觸發該事件。

適用版本:LSE 當前所有版本(含 v0.23.1)

LSE 插件中如何攔截玩家使用煙花等物品對方塊使用的行為?

監聽 onUseItemOn 事件(mc.listen("onUseItemOn", (player, item, block, side, pos) => {...})),在回調中按 item.type(如 "minecraft:firework_rocket")判斷後返回 false 即可攔截。

適用版本:LSE 當前所有版本(含 v0.23.1)

LSE 插件中想阻止苦力怕爆炸破壞方塊,寫 mc.listen("onEntityExplode", (entity)=>{ if(entity === creeper) return false; }) 不生效,應該怎麼寫?

onEntityExplode 回調原型是 function(source, pos, radius, maxResistance, isDestroy, isFire),第一個參數是實體對象,不能直接和名字比較,要用 source.type 取命名空間 ID:if (source.type == "minecraft:creeper") return false;。但在 onEntityExplode 中 return false 會攔截整個爆炸(不造成傷害也不破壞方塊)。

如果只想讓爆炸不破壞方塊:

  • 在服務器行為包中覆蓋苦力怕實體定義(creeper.json 裡 minecraft:explode 組件的 breaks_blocks 設為 false);
  • 或關閉遊戲規則 mobGriefing(會影響所有生物破壞行為);
  • 或使用現成的防爆插件。

onBlockExploded 事件不可攔截,不能用它來阻止方塊被炸。

適用版本:LSE 當前所有版本(含 v0.23.1)

LSE 插件在 onChat 中 return false 攔截了聊天,但聊天消息仍會輸出兩遍 / 仍能發出原版樣式消息,是什麼原因?

LSE 的事件攔截只是取消原版行為,不影響其他插件監聽到同一事件;LSE 事件沒有優先級,也不支持修改事件參數(onChat 回調只拿到 player 和 msg 字符串)。很多聊天插件會攔截後再按自己的格式重新發送一遍,因此多個聊天插件容易衝突,這種情況通常是另一個聊天插件攔截後又按原版樣式重發導致的。

解決:排查並卸載衝突的聊天插件;若需要多個插件依次修改聊天內容,可考慮基於 iListenAttentively 的第三方 LSE 擴展(如 ila-lse,事件參數通過 NBT 傳遞、可修改)。

適用版本:LSE 當前所有版本(含 v0.23.1)

LSE 插件裡通過發包創建的假容器(假箱子 GUI),玩家關閉時不會觸發 onCloseContainer 事件,怎麼監聽關閉?

onCloseContainer 只在玩家關閉真實存在的容器方塊時觸發;發包生成的假容器在服務端沒有對應容器方塊,因此不會觸發。

需要 hook 服務端處理客戶端 ContainerClosePacket 的函數(ServerNetworkHandler::handle(NetworkIdentifier const&, ContainerClosePacket const&))來獲取關閉事件,可用原生(C++)mod 實現,或使用提供數據包事件的第三方前置(如 GMLib)。LegacyRemoteCallApi 本身不提供事件。

LSE 的 onBlockChanged(方塊變化)事件能否通過 return false 攔截?LeviLamina C++ 中呢?

不能。LSE 的 onBlockChanged 是方塊已經改變後觸發的,不可攔截(文檔標註“攔截事件:不可以攔截”)。LeviLamina 的 ll::event::BlockChangedEvent 同樣不是可取消事件,C++ 中也沒有直接攔截方式,只能在方塊變化後再把方塊設置回原狀態,或自行 hook 具體的方塊修改來源(如玩家放置/破壞用對應的可攔截事件 onPlaceBlock、onDestroyBlock)。

適用版本:當前版本(LSE / LeviLamina)

LSE 的 onHopperPushOut 事件監聽不到漏斗之間的物品傳遞,有沒有能監聽漏斗間傳遞的事件?

LSE 只提供 onHopperSearchItem(漏斗/漏斗礦車吸取物品)和 onHopperPushOut(漏斗輸出物品)兩個漏斗事件,iListenAttentively 也沒有漏斗相關事件,沒有專門的“漏斗間物品傳遞”事件。需要的話可以寫 C++ mod 自行 hook:LSE 本身 hook 的是 Hopper::_tryPullInItemsFromAboveContainer(從上方容器吸入)、Hopper::_pushOutItems(向外推送)和 Hopper::_tryMoveInItem(實際移動物品),可以參考這些函數;涉及漏斗礦車時還需特殊處理其碰撞箱。

適用版本:LSE 0.23.x;iListenAttentively 當前版本

LSE 的 onMobHurt 回調裡的 damage 不是實體實際受到的傷害(無敵幀內的攻擊也被計入)?

是的。onMobHurt 在 Mob::_hurt 執行原邏輯之前觸發,給出的是傳入的原始傷害值,沒有經過護甲、附魔、藥水抗性、無敵幀等計算,所以無敵幀內的攻擊也會觸發並帶有傷害值。onAttackEntity 回調只有 (player, entity) 兩個參數,不提供傷害值。如需實際傷害,需要用 C++ mod 自行 hook 傷害結算後的位置來獲取。

LSE 的 onMobHurt 事件中,被骷髏/玩家用弓射出的箭擊中時,source 參數是射手還是箭?能拿到射手嗎?

onMobHurt(mob, source, damage, cause) 中,被箭等投射物擊中時 cause 為 ActorDamageCause.Projectile,source 為投射物實體(箭)而不是射手。LSE 目前沒有獲取投射物所有者(owner)的 API,所以無法直接通過該事件拿到射手,需要另想辦法(例如藉助其他插件/前置庫或 C++ mod 提供的接口)。

適用版本:LSE 0.23.x

LSE 腳本插件中,手機觸屏玩家“點擊屏幕”會觸發什麼事件?如何監聽?

觸屏操作對應的事件:長按屏幕觸發 onUseItem;點擊空氣相當於攻擊(左鍵),點擊方塊相當於交互,對方塊點擊會觸發 onUseItemOn(相當於右鍵方塊)。單純點擊空氣沒有對應的使用物品事件。如果要用物品打開菜單,可以改用長按,通過 mc.listen("onUseItem", ...) 監聽,這樣也能避免誤觸。

適用版本:當前版本(具體觸發行為取決於 BDS/客戶端觸屏操作方式)。未能從源碼或文檔中直接證實,僅供參考。

LSE 腳本插件卸載時,C++ 側通過 executeOnModUnload 註冊的回調不觸發,LSE 插件有 onUnload 回調嗎?

以前 LSE 卸載腳本插件時直接銷燬引擎,不會調用 ll::mod::Mod 的 onUnload,所以 executeOnModUnload 監聽不到。該問題已由 LSE PR #256(fix: fix plugin executeOnModUnload,2025-03-17 合併)修復。腳本側可以用 ll.onUnload(func) 註冊插件卸載時執行的清理函數。

適用版本:包含 PR #256 的 LSE 版本(2025-03 之後發佈的版本)及當前最新版

LSE JS 插件中有沒有服務器關閉時的事件監聽?

它不在 mc.listen 的事件列表裡,而是在“加載相關 API”(ll 對象)中:用 ll.onUnload(func) 註冊插件卸載回調,服務器關閉(插件卸載)時會被調用。該函數需要 LSE 0.9.6 及以上。

適用版本:LSE 0.9.6 及以上

如何用 LSE 禁止玩家使用某個物品?

監聽 onUseItem 事件(回調參數 player, item),判斷 item.type 是目標物品後在回調中 return false 攔截即可:

js
mc.listen('onUseItem', (player, item) => { if (item.type === 'minecraft:xxx') return false; });

如果是對方塊使用物品(右鍵方塊),還需要同時攔截 onUseItemOn。

如何用 LSE 腳本插件禁止玩家與某些方塊交互(例如領地內禁止打開唱片機、潛影盒)?為什麼提示消息會刷屏?

監聽 onUseItemOn 事件(回調參數 player, item, block, side, pos),判斷 block.type 為目標方塊時 return false 攔截交互。注意 Win10/PC 客戶端玩家右鍵一次會在服務端連續多次觸發該事件(文檔中有說明),若每次都 player.tell 會導致聊天欄刷屏:可以給發消息加防抖(debounce,最好做成與 player 解耦的通用防抖函數),或改為在物品欄上方(actionbar)提示。

如何讓 LSE 腳本插件在服務器啟動完成後自動執行一些命令?

監聽 onServerStarted 事件並在回調裡調用 mc.runcmd:mc.listen("onServerStarted", () => { mc.runcmd("你的命令"); });,需要執行多條命令就寫多個 mc.runcmd()。若需要獲取命令輸出可用 mc.runcmdEx。

怎麼用插件阻止服務器裡的液體流動?

監聽 LSE 的 onLiquidFlow 事件(回調參數 from: Block, to: IntPos)並返回 false 攔截:

js
mc.listen('onLiquidFlow', (from, to) => false);

也可以寫 native mod 去掉液體 tick。

適用版本:當前版本(該事件依賴 iListenAttentively,隨 LSE 一起安裝)

想做告示牌鎖箱子功能,用 LSE 應該攔截哪些行為?

監聽玩家打開容器事件 mc.listen("onOpenContainer", (player, block) => ...)(或方塊交互 onUseItemOn),非主人時 return false 攔截;同時還必須攔截漏斗和漏斗礦車從箱子中抽取物品:監聽 onHopperSearchItem(回調參數 pos, isMinecart, item,return false 即無法吸取),否則可以用漏斗繞過鎖。

適用版本:LegacyScriptEngine 0.23.x

生物受傷事件(LSE 的 onMobHurt / GMLIB-LRCA 的 onMobHurted)給出的傷害值是減免前還是減免後的最終傷害?

LSE 自帶的 onMobHurt(回調 function(mob,source,damage,cause))是 hook Mob::_hurt 實現的,damage 是傳入 _hurt 的原始傷害值,即護甲、保護附魔、抗性效果等減免之前的值。

第三方 GMLIB-LRCA 的 onMobHurted 據其說明給出的是經過護甲、魔咒、抗性減免之後的值,但它仍不是最終值:處於受擊間隔(無敵幀)時實際傷害會歸零而事件未計入;攻擊創造模式玩家也會觸發事件但對方不受傷。需要精確的實際傷害時,可以在事件後(如下一 tick)讀取實體血量(或 NBT 中的 Health)的前後差值來計算。

適用版本:當前版本(onMobHurt);GMLIB 部分為第三方插件行為。未能從源碼或文檔中直接證實,僅供參考。

用 LSE 腳本如何禁止玩家修改告示牌?

LSE 沒有專門的告示牌編輯事件。可以監聽 onUseItemOn(或 onBlockInteracted),判斷目標方塊為告示牌(block.type 包含 sign)時 return false 攔截交互,從而阻止打開編輯界面。若要攔截客戶端發來的告示牌編輯數據包,純 LSE 沒有收包攔截事件,需要藉助 iListenAttentively 等擴展或用 C++ mod 實現。

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

用 LSE 寫插件時如何檢測玩家在鐵砧中重命名/輸入的內容?onOpenContainerScreen 能觸發但 onContainerChange 對鐵砧無效。

純 LSE API 無法實現,鐵砧不屬於普通容器,LSE 也沒有鐵砧重命名事件。需要依賴 iListenAttentively(ila)以及其 LSE 導出插件 iListenAttentively-LseExport(ila-lseexport,https://github.com/MiracleForest/iListenAttentively-LseExport),通過監聽其導出的底層事件實現;或者直接用 C++ 寫原生 mod。

適用版本:LSE 當前版本

LSE JS 插件在 onBlockExplode 監聽器裡調用 mc.explode(或在獲取經驗事件裡再加經驗)導致服務器崩潰/卡死,原因是什麼?

這是插件自身造成的死循環:事件回調裡調用的 API 會再次觸發同一事件(mc.explode 會再次觸發 onBlockExplode,通過 API 加經驗也會觸發玩家獲取經驗事件),形成無限遞歸。LSE 不會區分事件是否由插件自己觸發,文檔中也有提醒。解決辦法:在插件裡設一個布爾標誌,自己發起爆炸/加經驗期間跳過處理,或改用不會重複觸發的方式。

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