API de CannonRTP

CannonRTP expone tres eventos de Bukkit para que otros plugins puedan engancharse. Todos los eventos viven en el paquete com.magmaguy.cannonrtp.api y se disparan en el hilo principal del servidor.

Para escuchar, registra un @EventHandler normal de Bukkit -- no hay un paso de registro adicional.

CannonRTPLaunchEvent

Se dispara en el momento en que un jugador está a punto de comenzar una secuencia de lanzamiento del cañón, antes de que se apliquen visuales o efectos. Cancelable.

Propiedad	Tipo	Descripción
player	Player	El jugador que activó el cañón
cannonId	String	El id de configuración (nombre de archivo sin .yml) del cañón
cannonDisplayName	String	El campo displayName del cañón
cannonLocation	Location	La colocación exacta que se activó
destination	Location	La ubicación de aterrizaje segura previamente validada elegida para este lanzamiento

Cancelar el evento aborta el lanzamiento por completo: el jugador permanece donde está, no se aplican efectos y el destino se devuelve al frente de la cola del cañón para reutilizarlo en el siguiente lanzamiento. Útil para listas negras basadas en regiones, plugins de cooldown, puertas de economía o verificaciones de regiones PvP.

@EventHandler
public void onLaunch(CannonRTPLaunchEvent event) {
    if (event.getPlayer().getWorld().getName().equals("event_world")) {
        event.setCancelled(true);
    }
}

CannonRTPLocationValidationEvent

Se dispara para cada ubicación de aterrizaje candidata mientras CannonRTP la valida durante la búsqueda de precarga. Se dispara solo después de que todas las verificaciones internas (borde del mundo, superficie, materiales inseguros, integraciones de protección) hayan pasado.

Propiedad	Tipo	Descripción
cannonId	String	El id de configuración del cañón que está realizando la búsqueda
cannonDisplayName	String	El campo displayName del cañón
candidate	Location	La ubicación de aterrizaje candidata que se está considerando

Este evento no es cancelable en el sentido de Bukkit. Para vetar un candidato, llama a:

event.setRejected("inside arena spawn protection");

CannonRTP entonces descartará el candidato como si hubiera fallado una verificación interna y continuará la búsqueda. Los listeners pueden implementar reglas de región personalizadas más allá de los adaptadores de protección integrados.

Nota: se dispara en el hilo principal durante los intentos de precarga (uno por tick globalmente, round-robin entre los cañones activos). Mantén el handler rápido.

CannonRTPLandingEvent

Se dispara después de que un jugador haya sido teletransportado al destino y la secuencia de lanzamiento haya finalizado por completo (la fase LANDING ha terminado, se ha eliminado Caída Lenta y se ha reproducido la ráfaga de impacto). No cancelable -- usa CannonRTPLaunchEvent para vetar un lanzamiento antes de que ocurra.

Propiedad	Tipo	Descripción
player	Player	El jugador que acaba de aterrizar
cannonId	String	El id de configuración del cañón que lo lanzó
cannonDisplayName	String	El campo displayName del cañón
destination	Location	Una copia del destino al que fue enviado

Útil para otorgar recompensas a la primera llegada, activar efectos posteriores, conceder permisos de región, anunciar llegadas o analítica.

Hilos y Ciclo de Vida

• Los tres eventos se despachan en el hilo principal.
• CannonRTPLocationValidationEvent se despacha durante el tick global de precarga (un intento por tick del servidor, round-robin entre los cañones activos), por lo que el trabajo pesado en los listeners ralentizará visiblemente la rapidez con la que los cañones cargan sus colas.
• CannonRTPLaunchEvent se despacha inmediatamente antes de que se construya una LaunchSequence, por lo que cualquier estado que mutes (efectos de poción, inventario, modo de juego) surtirá efecto antes de que comience la fase de búsqueda.
• CannonRTPLandingEvent se despacha una vez por lanzamiento, en el tick de la fase LANDING, después de la ráfaga de impacto.

Trabajando con cannonId

cannonId es el mismo id usado por todos los comandos de administración (/wc place, /wc target, etc.) y coincide con el nombre del archivo de configuración del cañón sin .yml. Ten en cuenta que una sola configuración de cañón puede gestionar muchas colocaciones en el mundo; todas comparten el mismo cannonId y cannonDisplayName. Si necesitas la colocación exacta, usa cannonLocation de CannonRTPLaunchEvent.