跳到主要内容

事件监听器

事件是监听游戏中发生的特定动作的有效方式。它们可以由服务器或插件调用。 当某些事情发生时，比如玩家加入服务器或方块被破坏时，这些事件会被服务器或插件调用。 插件可以调用自定义事件，比如玩家完成任务，供其他插件监听。

你的监听器类​

要监听事件，你需要创建一个实现 Listener 的类。 这个类可以随意命名，但建议使用与你要监听的事件相关的名称。

ExampleListener.java
public class ExampleListener implements Listener {
    // ...
}

@EventHandler​

要监听一个事件，你需要创建一个带有 @EventHandler 注解的方法。 这个方法可以随意命名，但建议使用与它监听的事件相关的有意义的名称。

监听器方法​

方法体不需要返回任何数据，因此使用 void 作为返回类型。 监听器接受一个参数，即被监听的事件。

ExampleListener.java
public class ExampleListener implements Listener {

    @EventHandler
    public void onPlayerMove(PlayerMoveEvent event) {
        // ...
    }
}
事件

没有可以监听的事件列表，但是你可以看看 这里 来查看所有继承 Event 的类。

一个事件只有在有静态 getHandlerList 方法时才能被监听。

注册监听器​

要注册监听器，你需要调用 Bukkit.getPluginManager().registerEvents() 并传入你的监听器类实例和你的插件实例。

这将注册你的监听器类并允许它监听事件。 这通常在你的插件的 onEnable() 方法中完成，这样它就会在服务器开始运行时注册。

ExamplePlugin.java
public class ExamplePlugin extends JavaPlugin {

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(new ExampleListener(), this);
    }
}

事件优先级​

你也可以指定事件的优先级。

ExampleListener.java
public class ExampleListener implements Listener {

    @EventHandler(priority = EventPriority.HIGH)
    public void onPlayerMove(PlayerMoveEvent event) {
        // ...
    }
}

有六种不同的优先级可以使用：

优先级的顺序有点反直觉。优先级越高，事件被调用的时间越晚。 例如，如果你的插件在某个事件中需要最后发言权 - 以避免它被改变 - 你 应该使用 EventPriority.HIGHEST。

备注

MONITOR 优先级用于监控事件，但不改变它。它在所有其他优先级被调用后调用。 这意味着你可以获取任何插件交互的结果，比如取消或修改。

事件取消​

某些事件可以被取消，防止给定的动作完成。 这些事件实现了 Cancellable。

ExampleListener.java
public class ExampleListener implements Listener {

    @EventHandler
    public void onPlayerMove(PlayerMoveEvent event) {
        event.setCancelled(true);
    }
}
注意

重要的是要考虑到在你的插件被调用之前，另一个插件可能已经取消或改变了事件。 在对事件做任何操作之前，始终要检查事件。

上面的例子将取消事件，这意味着玩家将不能移动。 一旦事件被取消，它将继续调用该事件的任何其他监听器，除非它们在 @EventHandler 注解中添加 ignoreCancelled = true 来忽略已取消的事件。

ExampleListener.java
public class ExampleListener implements Listener {

    @EventHandler(ignoreCancelled = true)
    public void onPlayerMove(PlayerMoveEvent event) {
        // ...
    }
}