Events

Events are used to detect and respond to changes that occur in the game or on the server. For example, you can have an event that is called when a player breaks a block, or when a chat message is sent.

Prison utilizes the EventBus library in Google Guava to power the events system. It's incredibly simple to get started with.

Listening for events

Defining your event listeners

An event listener is a method that is run each time an event occurs in the game. To define an event listener, you must create a method with the only parameter being the event class, and then annotate it with @Subscribe. Here is an example:

@Subscribe
public void onPlayerJoin(PlayerJoinEvent event) {
     // Greet a player when they log on
     Player player = event.getPlayer();
     player.sendMessage("Welcome back!");
}

This method will be called each time a player joins the server. Of course, different events have different data stored inside them, and you can view them in the Event Javadocs.

Registering your event listeners

You may have as many event listeners in a class as you wish. However, you must register each class that contains event listeners so that the EventBus knows to check your class for event listeners. Here's how to do that:

// ...
Prison.get().getEventBus().register(new MyListenerClass());

Canceling events

Some events can be canceled. Canceling an event prevents the event it represents from occurring in the game. For example, you can prevent players from chatting like so:

public void globalMute(PlayerChatEvent event) {
   event.setCanceled(true); // The chat message will not send
}

This works for any event implementing the Cancelable interface.

Making your own events

Writing your event class

It's very easy to make your own event. Let's make an event that's dispatched whenever a mine is reset.

public class MineResetEvent {
    
    private Mine mine;

    public MineResetEvent(Mine mine) {
        this.mine = mine;
    }

    public Mine getMine() {
        return mine;
    }

}

That's your event! Notice that it does not need to extend or implement anything - it's just a simple bean. Now, if you want to make this event cancelable, you may do this by implementing the Cancelable interface:

public class MineResetEvent {
    
    private Mine mine;
    private boolean canceled = false; // false by default

    public MineResetEvent(Mine mine) {
        this.mine = mine;
    }

    public Mine getMine() {
        return mine;
    }

    // Implement these two methods
    
    @Override public boolean isCanceled() {
        return canceled;
    }

    @Override public void setCanceled(boolean canceled) {
        this.canceled = canceled;
    }

}

Calling your event

Your event won't do anything unless it's called. Calling an event in the EventBus is called posting. To post our event, simply call this method:

// ...
Prison.get().getEventBus().post(new MineResetEvent(ourMine)); // Call the event
ourMine.reset(); // And then reset our mine after the event is called

It's that simple! The object you pass into post() will be passed into all the event listeners as-is, so your data will persist for all listeners of your event.

Note that if your event is cancelable, you need check to ensure that your isCanceled() method returns false.

// ...
MineResetEvent event = new MineResetEvent(ourMine);
Prison.get().getEventBus().post(event);
if(!event.isCanceled()) ourMine.reset(); // This will only run if the event isn't canceled

Hooray! Now, you're an expert at the events system in Prison Core.