# Events

## Custom Events

### PlayerAnchorDeathEvent

This event is triggered when a player dies from a detonated Respawn Anchor. It provides information about the block, the player that died and the player who detonated the Respawn Anchor.

There are plans to let you change the death message, etc just like in `PlayerCrystalDeathEvent`

```java
@EventHandler
public void onAnchorDeath(@NotNull PlayerAnchorDeathEvent event) {
    Player detonatorAttacker = event.attacker();
    Player deadVictim = event.victim();
    @Nullable RespawnAnchor anchor = event.anchor();
    BlockState block = event.block();
    
    // Do whatever you want to do.
}
```

* `attacker()` - Retrieves the Respawn Anchors detonator.
* `victim()` - Retrieves the player that died to the Respawn Anchor explosion detonated by the attacker.
* `anchor()` - Retrieves the (already exploded) Respawn Anchor
* `block()` - Retrieves the `BlockState` of the nullable block.

### PlayerCrystalDeathEvent

This event is triggered when a player dies from a destroyed end crystal. It provides information about the end crystal, the player that died and the player who destroyed the end crystal.

This class lets you change the death message, etc.

```java
@EventHandler
public void onAnchorDeath(@NotNull PlayerCrystalDeathEvent event) {
    Player killer = event.killer();
    Player victim = event.victim();
    Entity entity = event.crystal();

    // Do whatever you want to do.
}
```

* `killer()` - Retrieves the End Crystals destroyer.
* `victim()` - Retrieves the player that died to the End Crystal explosion caused by the killer/attacker.
* `crystal()` - Retrieves the End Crystal associated with this event.

## Abstract Event Listener

This is a easy way to automatically register your event listeners.

This currently only supports one singular event per class.

Let's make a `PlayerJoinEvent` listener.

```java
package dev.manere.example;

import dev.manere.utils.event.EventListener;
import org.bukkit.event.player.PlayerJoinEvent;
import org.jetbrains.annotations.NotNull;

public class JoinListener extends EventListener<PlayerJoinEvent> {
    public JoinListener() {
        super(PlayerJoinEvent.class);
    }

    @Override
    protected void execute(@NotNull PlayerJoinEvent event) {
        // Do literally anything with the event
    }
}
```

## Event Builder

The `EventBuilder` is an easy way to create a event listener without creating any new methods, instead by just using a Consumer.

Let's also make a `PlayerJoinEvent` listener.

```java
EventBuilder.event(PlayerJoinEvent.class)
    .execute(event -> {
        // Do anything you want to do with the PlayerJoinEvent.
    })
    .build() // EventHandler<PlayerJoinEvent>
    .ignoreCancelled(false) // Default
    .priority(400) // Alternatively: .priority(EventPriority.NORMAL), Default
    .register(); // EventCallback<PlayerJoinEvent>
```

* `execute(Consumer<E>)` - What should be ran when listening to a event.
* `build()` - Returns the `EventHandler<E>` which configures your event listener options.&#x20;
* `ignoreCancelled(boolean)` - Sets whether cancelled events should be ignored.
* `priority(int)` - Sets the event priority.
* `register()` - Finally registers the event.

{% hint style="info" %}
If you're using the default values of the event listener, you can skip `build()` and run `register()` instead.

Updated code:

```java
EventBuilder.event(PlayerJoinEvent.class)
    .execute(event -> {
        // Do anything you want to do with the PlayerJoinEvent.
    })
    .register(); // EventCallback<PlayerJoinEvent>
```

{% endhint %}

## `PluginWrapper` Events

In `PluginWrapper` you will find a `events()` method which returns `PluginEvents`. It's an alternative to the `PluginManager`.

Here's the example `PlayerJoinEvent` listener.

```java
public class TestPlugin extends PluginWrapper {
    @Override
    protected void start() {
        events().register(PlayerJoinEvent.class, event -> {
            // Whatever you want to do with the PlayerJoinEvent.
        });
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://manered.gitbook.io/utils/docs/events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.