> For the complete documentation index, see [llms.txt](https://realisticnode.gitbook.io/rnsetups/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://realisticnode.gitbook.io/rnsetups/rncombatpvp/reference/api.md).

# Developer API

The events other plugins can listen to.

rnCombatPvP fires three Bukkit events, in the package `com.realisticnode.rncombat.api`. Add the rnCombatPvP jar to your project as a compile-only dependency, and `rnCombatPvP` to `depend` or `softdepend` in your `plugin.yml`.

## CombatTagEvent

A player is about to **enter** combat. It is not fired when a fight that is already going on is only renewed by another hit. **Cancellable**: cancel it to keep the player out of combat.

| Method                                    | What it gives                                                       |
| ----------------------------------------- | ------------------------------------------------------------------- |
| `getPlayer()`                             | The player                                                          |
| `getEnemy()`                              | Who they fight: a player, a mob, or `null` when tagged by a command |
| `getSeconds()` / `setSeconds(int)`        | The combat time (at least 1)                                        |
| `isCancelled()` / `setCancelled(boolean)` | Cancel the tag                                                      |

```java
@EventHandler
public void onTag(CombatTagEvent event) {
    // nobody is put in combat inside an event arena
    if (arenas.isInArena(event.getPlayer())) {
        event.setCancelled(true);
    }
}
```

## CombatUntagEvent

A player **left** combat. `getReason()` tells why:

| Reason         | When                                                      |
| -------------- | --------------------------------------------------------- |
| `EXPIRED`      | The time ran out                                          |
| `DEATH`        | The player died                                           |
| `ENEMIES_GONE` | Every enemy died or left (`combat.end-when-enemies-gone`) |
| `COMMAND`      | `/combat untag`                                           |
| `QUIT`         | The player left the server                                |
| `PLUGIN`       | Other causes                                              |

## CombatLogEvent

A player left the server while in combat and is **about to be punished**. It is fired before the money penalty, the commands and the NPC. It can't be cancelled; use `rncombat.bypass.combatlog` for players who should not be punished.

| Method            | What it gives                                                     |
| ----------------- | ----------------------------------------------------------------- |
| `getPlayer()`     | The player who left                                               |
| `getPunishment()` | `NPC`, `KILL` or `NOTHING` (the value of `combat-log.punishment`) |

```java
@EventHandler
public void onCombatLog(CombatLogEvent event) {
    getLogger().info(event.getPlayer().getName() + " logged out in combat (" + event.getPunishment() + ")");
}
```

{% hint style="info" %}
On Folia the events are fired on the thread of the player's region.
{% endhint %}