跳到正文
本頁目錄

監聽事件

插件通過事件對遊戲做出反應:玩家加入、發送聊天消息、破壞方塊。本指南介紹如何監聽事件、如何阻止遊戲處理事件,以及如何找到你需要的事件。

你需要一個能加載的插件:見寫你的第一個腳本插件。 示例使用 JavaScript;API 在每種語言中都相同。

1. 監聽事件

用事件名和每次事件發生時要調用的函數調用 mc.listen。在入口腳本的頂層調用它,這樣插件加載時就會註冊監聽器:

JavaScript
mc.listen("onJoin", (player) => {
    player.tell(`Welcome, ${player.name}!`);
    log(`${player.name} has joined the server.`);
});

函數會得到事件的參數:onJoin 傳入進入遊戲的玩家。每個事件的頁面都給出了它的參數,例如 onJoin 見玩家相關事件。

用 Lua 寫同樣的監聽器:

Lua
mc.listen("onJoin", function(player)
    mc.broadcast(player.name .. " has joined the server.")
end)

如果無法註冊監聽器,例如事件名不存在,mc.listen 返回 false。

2. 攔截事件

許多事件可以被攔截:它們的頁面寫有「攔截事件:函數返回 false」。在監聽器中返回 false,遊戲就不再處理這個事件, 就像它沒有發生過一樣。下面的監聽器會丟棄包含某個詞的聊天消息:

JavaScript
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。使用這類值之前先檢查:

JavaScript
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。先檢查輸入再行動,或者改用另一個事件。

找到你需要的事件

事件按主題列出:

事件監聽 API 描述了 mc.listen 本身。