> 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/rnkoth/reference/api.md).

# Developer API

Events other plugins can listen to, to react to KOTH starts, captures and ends.

rnKoth fires three Bukkit events that other plugins can listen to. They are in the package `com.realisticnode.rnkoth.api`.

## Events

### KothStartEvent

A KOTH is about to open (after its countdown). It can be **cancelled** to stop the start.

| Method                                    | Returns                                                                              |
| ----------------------------------------- | ------------------------------------------------------------------------------------ |
| `getHill()`                               | Name of the KOTH (its file name in `koths/`)                                         |
| `isScheduled()`                           | `true` when started by its schedule, `false` when started by a command or the editor |
| `isCancelled()` / `setCancelled(boolean)` | Cancel the start                                                                     |

When a start from `/koth start` without countdown is cancelled, the admin sees `Another plugin stopped the start.` Every cancelled start (also after a countdown or by the schedule) is logged in the console: `The start of KOTH spawn was cancelled by another plugin (KothStartEvent).`

### KothCaptureEvent

A player or team started gaining a KOTH: it took control of it, or took it from another side.

| Method         | Returns                                                       |
| -------------- | ------------------------------------------------------------- |
| `getHill()`    | Name of the KOTH                                              |
| `getHolder()`  | Player or team name, without colors                           |
| `getPlayers()` | `List<UUID>` of the players of that side standing in the KOTH |

### KothEndEvent

An event ended.

| Method         | Returns                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getHill()`    | Name of the KOTH                                                                                                                                                 |
| `getReason()`  | `WON`, `TIME_UP` (ended without a winner) or `STOPPED` (stopped by an admin, or the KOTH was deleted: by command, in the editor or by removing its file by hand) |
| `getWinner()`  | Winning player or team name, or `null`                                                                                                                           |
| `getWinners()` | `List<UUID>` of the players who get the winner rewards (empty without a winner)                                                                                  |

## Example

```java
import com.realisticnode.rnkoth.api.KothEndEvent;
import com.realisticnode.rnkoth.api.KothStartEvent;
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class KothListener implements Listener {

    @EventHandler
    public void onStart(KothStartEvent event) {
        // No arena event while the whitelist is on (maintenance)
        if (event.getHill().equals("arena") && Bukkit.hasWhitelist()) {
            event.setCancelled(true);
        }
    }

    @EventHandler
    public void onEnd(KothEndEvent event) {
        if (event.getReason() == KothEndEvent.Reason.WON) {
            Bukkit.getLogger().info(event.getWinner() + " won " + event.getHill());
        }
    }
}
```

## Adding rnKoth to your project

rnKoth is not published in a Maven repository. Use the plugin jar as a compile-only dependency:

**Gradle**

```groovy
dependencies {
    compileOnly files('libs/rnKoth.jar')
}
```

**Maven**: install the jar in your local repository once, then add it with `provided` scope.

```
mvn install:install-file -Dfile=rnKoth.jar -DgroupId=com.realisticnode -DartifactId=rnKoth -Dversion=1.0.1 -Dpackaging=jar
```

```xml
<dependency>
    <groupId>com.realisticnode</groupId>
    <artifactId>rnKoth</artifactId>
    <version>1.0.1</version>
    <scope>provided</scope>
</dependency>
```

Then add rnKoth to your `plugin.yml`, so it loads before your plugin:

```yaml
softdepend: [rnKoth]   # or depend: [rnKoth] if your plugin needs it
```

{% hint style="info" %}
The events are fired synchronously on a server thread: the main thread on Spigot and Paper. On Folia it is usually the global region thread (or the thread of the player who ran a command), so do not change players directly from them there; use the player's own scheduler.
{% endhint %}