監聽事件
插件通過事件對遊戲做出反應:玩家加入、發送聊天消息、破壞方塊。本指南介紹如何監聽事件、如何阻止遊戲處理事件,以及如何找到你需要的事件。
你需要一個能加載的插件:見寫你的第一個腳本插件。 示例使用 JavaScript;API 在每種語言中都相同。
1. 監聽事件
用事件名和每次事件發生時要調用的函數調用 mc.listen。在入口腳本的頂層調用它,這樣插件加載時就會註冊監聽器:
mc.listen("onJoin", (player) => {
player.tell(`Welcome, ${player.name}!`);
log(`${player.name} has joined the server.`);
});函數會得到事件的參數:onJoin 傳入進入遊戲的玩家。每個事件的頁面都給出了它的參數,例如 onJoin 見玩家相關事件。
用 Lua 寫同樣的監聽器:
mc.listen("onJoin", function(player)
mc.broadcast(player.name .. " has joined the server.")
end)如果無法註冊監聽器,例如事件名不存在,mc.listen 返回 false。
2. 攔截事件
許多事件可以被攔截:它們的頁面寫有「攔截事件:函數返回 false」。在監聽器中返回 false,遊戲就不再處理這個事件,
就像它沒有發生過一樣。下面的監聽器會丟棄包含某個詞的聊天消息:
mc.listen("onChat", (player, msg) => {
if (msg.includes("badword")) {
player.tell("Please keep the chat friendly.");
return false;
}
});這條消息不會顯示給任何人。不返回任何值(或返回 false 以外的值)就會放行事件。
攔截只會阻止遊戲。其他插件對同一事件的監聽器仍會被調用:LSE 按註冊順序調用一個事件的所有監聽器,一般就是插件的加載順序。
要讓你的監聽器先於另一個插件的運行,就讓那個插件在它的 manifest.json 中依賴你的插件(見插件與引擎)。
3. 檢查拿到的值
有些參數可能為 Null:玩家死亡事件會傳入殺死玩家的實體,沒有實體造成死亡時它為
Null。使用這類值之前先檢查:
mc.listen("onPlayerDie", (player, source) => {
if (source) {
log(`${player.name} was killed by ${source.name}.`);
} else {
log(`${player.name} died.`);
}
});讓監聽器保持簡短。它們在服務器線程上運行,慢的監聽器會拖住服務器,對 onTick 這類頻繁的事件更是如此。
4. 避免死循環
一個會再次引發自身事件的監聽器永遠不會結束。例如,調用 mc.runcmd 的 onConsoleCmd 監聽器會再次觸發
onConsoleCmd。先檢查輸入再行動,或者改用另一個事件。
找到你需要的事件
事件按主題列出:
- 玩家相關事件:加入、離開、聊天、命令、死亡、使用物品……
- 實體相關事件和方塊相關事件。
- 經濟系統事件:金錢的變化。
- 其他事件:服務器啟動(
onServerStarted)、每個遊戲刻(onTick)、控制台命令、計分板分數。
事件監聽 API 描述了 mc.listen 本身。