Event API

Introduction

VoxelSniper Reimagined offers a unique, multiplatform Event API compared to Forge mods and Bukkit plugins. This API can be used to listen to, and modify the actions VoxelSniper performs.

The events

Currently, VoxelSniper Reimagined offers the following events:

• PlayerMaterialChangedEvent
• PlayerReplaceMaterialChangedEvent
• PlayerBrushChangedEvent
• PlayerBrushSizeChangedEvent
• PlayerSnipeEvent

PlayerMaterialChangedEvent

This event is called whenever a player changes their voxel material (for example using /v )

available methods:

getOldMaterial()
getNewMaterial()

PlayerReplaceMaterialChangedEvent

This event is called whenever a player changes their voxel replace material (for example using /vr )

available methods:

getOldMaterial()
getNewMaterial()

PlayerBrushChangedEvent

This event is called whenever a player changes their active brush (for example /b ball)

available methods:

getOldBrush()
getNewBrush()
getToolId()

PlayerBrushSizeChangedEvent

This event is called whenever a player changes their active brushes size (for example /b 5)

available methods:

getOldSize()
getNewSize()
getToolId()
getBrush()

PlayerSnipeEvent

This event is called whenever a player uses their brush (for example using the arrow or gunpowder). The positions list can be modified in order to disallow certain locations from being modified (area protection)

available methods:

getBrush()
getOperations()
getStatus()

The playerSnipeEvent contains a list of operations that can be checked in the event.

Listening for Events

In order to listen for events, we need to register a listener on the _HandlerList _of the event:

PlayerSnipeEvent.getHandlerList().registerListener(EventPriority.HIGH, (ev) -> {
	// do stuff
});

The EventPriority could be HIGH, MEDIUM or LOW. Listeners with a low priority will be called first, followed by the Listeners with a medium priority. Listeners with a high priority will be called last. This is especially useful if an event can be altered by listeners (for example if an event is cancellable). This way, you could ensure a logging listener is always called when last.
cancellable can be cancelled by calling event.setCancelled(true).
The EventPriority coulld also be omitted entirely. In this case, the EventPriority will default to MEDIUM.

PlayerSnipeEvent.registerListener(ev -> {
	// do stuff
});

Instead of an lambda, a method reference could also be used, as long as the method signature matches that of a Consumer.

public void registerEvents() {
	PlayerReplaceMaterialChangedEvent.registerListener(this::handleEvent);
}

private void handleEvent(PlayerReplaceMaterialChangedEvent ev) {
	ev.getPlayer().sendMessage("Test SniperReplaceMaterialChangedEvent in function");
}

The example code could also be found here: here

Cancelling events

Most events can be cancelled using the setCancelled method. The remaining listeners will not get the event if this is the case. In case of the PlayerSnipeEvent, the individual operations can also be cancelled.

Examples

Disallow any grass blocks to be changed

PlayerSnipeEvent.registerListener(event -> {
    event.getOperations().forEach(operations-> {
        if(operations instanceof BlockOperation && ((BlockOperation) operations).getOldData().getMaterial() == VoxelMaterial.GRASS_BLOCK) {
            operations.setCancelled(true);
        }
    });
});

Cancel any snipe event (Why would you use this)

PlayerSnipeEvent.registerListener(event -> {
    event.setCancelled(true);
    Bukkit.broadcastMessage("Cancelled event");
});

Creating Events

In order to create an event, you should create a new class that extends com.github.kevindagame.voxelsniper.events.Event or any of it's subclasses.
When an event is cancellable, it should also implement com.github.kevindagame.voxelsniper.events.Cancellable.
Every event class should have a static final field, replacing classname with the classname of the event you are creating:

private static final HandlerList<classname> handlers = new HandlerList<>();

This HandlerList should then be returned in the instance method getHandlers and the static method getHandlerList, replacing classname with the classname of the Event you are creating:

public static HandlerList<classname> getHandlerList() {
    return handlers;
}

@Override
protected HandlerList<classname> getHandlers() {
    return handlers;
}

HandlerList should be imported from com.github.kevindagame.voxelsniper.events.
Example event classes could be found here.