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

# API para desarrolladores

Eventos que pueden escuchar otros plugins para reaccionar a los inicios, capturas y finales de los KOTHs.

rnKoth lanza tres eventos de Bukkit que otros plugins pueden escuchar. Están en el paquete `com.realisticnode.rnkoth.api`.

## Eventos

### KothStartEvent

Un KOTH está a punto de abrirse (después de su cuenta atrás). Se puede **cancelar** para impedir el inicio.

| Método                                    | Devuelve                                                                            |
| ----------------------------------------- | ----------------------------------------------------------------------------------- |
| `getHill()`                               | Nombre del KOTH (el nombre de su archivo en `koths/`)                               |
| `isScheduled()`                           | `true` cuando lo inició su horario, `false` cuando lo inició un comando o el editor |
| `isCancelled()` / `setCancelled(boolean)` | Cancelar el inicio                                                                  |

Cuando se cancela un inicio de `/koth start` sin cuenta atrás, el admin ve `Otro plugin canceló el inicio.` Cada inicio cancelado (también después de una cuenta atrás o por el horario) queda registrado en la consola: `The start of KOTH spawn was cancelled by another plugin (KothStartEvent).`

### KothCaptureEvent

Un jugador o equipo empezó a avanzar en un KOTH: tomó el control, o se lo quitó a otro bando.

| Método         | Devuelve                                                        |
| -------------- | --------------------------------------------------------------- |
| `getHill()`    | Nombre del KOTH                                                 |
| `getHolder()`  | Nombre del jugador o del equipo, sin colores                    |
| `getPlayers()` | `List<UUID>` de los jugadores de ese bando que están en el KOTH |

### KothEndEvent

Terminó un evento.

| Método         | Devuelve                                                                                                                                                 |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getHill()`    | Nombre del KOTH                                                                                                                                          |
| `getReason()`  | `WON`, `TIME_UP` (terminó sin ganador) o `STOPPED` (lo detuvo un admin, o se eliminó el KOTH: con un comando, en el editor o borrando su archivo a mano) |
| `getWinner()`  | Nombre del jugador o equipo ganador, o `null`                                                                                                            |
| `getWinners()` | `List<UUID>` de los jugadores que reciben los premios del ganador (vacía si no hay ganador)                                                              |

## Ejemplo

```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) {
        // Sin evento en la arena mientras la whitelist está activada (mantenimiento)
        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());
        }
    }
}
```

## Añadir rnKoth a tu proyecto

rnKoth no está publicado en un repositorio de Maven. Usa el jar del plugin como dependencia solo de compilación:

**Gradle**

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

**Maven**: instala el jar en tu repositorio local una vez y luego añádelo con el scope `provided`.

```
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>
```

Luego añade rnKoth a tu `plugin.yml`, para que cargue antes que tu plugin:

```yaml
softdepend: [rnKoth]   # o depend: [rnKoth] si tu plugin lo necesita
```

{% hint style="info" %}
Los eventos se lanzan de forma síncrona en un hilo del servidor: el hilo principal en Spigot y Paper. En Folia suele ser el hilo de la región global (o el hilo del jugador que usó un comando), así que ahí no cambies a los jugadores directamente desde ellos; usa el scheduler propio del jugador.
{% endhint %}