API de CannonRTP

La referencia Java generada permite buscar clases, métodos y firmas, e indica la versión y el commit del código fuente de cada módulo.

CannonRTP expone tres eventos Bukkit para integrar otros plugins. Todos están en com.magmaguy.cannonrtp.api y se emiten en el hilo principal del servidor.

Para escucharlos, registra un @EventHandler normal de Bukkit; no hay un paso adicional de registro.

CannonRTPLaunchEvent

Se emite cuando un jugador va a iniciar la secuencia de lanzamiento, antes de aplicar elementos visuales o efectos. Se puede cancelar.

Propiedad	Tipo	Descripción
player	Player	Jugador que ha activado el cañón
cannonId	String	ID de configuración del cañón, su nombre de archivo sin .yml
cannonDisplayName	String	Campo displayName del cañón
cannonLocation	Location	Colocación exacta que se ha activado
destination	Location	Ubicación segura de aterrizaje previamente validada para este lanzamiento

Cancelar el evento interrumpe por completo el lanzamiento: el jugador permanece donde está, no se aplican efectos, no empieza el tiempo de reutilización integrado y el destino vuelve al principio de la cola. Para no emitir un evento cancelado repetidamente en cada tick de detección de jugadores, CannonRTP aumenta la espera entre reintentos de 1 a 30 segundos mientras el jugador siga dentro del radio. Salir del radio o completar un lanzamiento aceptado elimina esa espera. Sirve para exclusiones por región, plugins de tiempos de reutilización, requisitos económicos o comprobaciones de regiones PvP.

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

CannonRTPLocationValidationEvent

Se emite para cada ubicación candidata durante la búsqueda de precarga, y de nuevo para el destino consumido cuando se revalida al confirmar el lanzamiento, justo antes del teletransporte de descenso. Durante la precarga, se emite después de superar las comprobaciones del borde del mundo, superficie, materiales inseguros y protecciones. Al confirmar el lanzamiento, se vuelven a comprobar la referencia actual del mundo, la columna de aterrizaje y las integraciones de protección antes del evento. Esta segunda ruta no repite la comprobación del borde del mundo.

Propiedad	Tipo	Descripción
cannonId	String	ID de configuración del cañón que realiza la búsqueda
cannonDisplayName	String	Campo displayName del cañón
candidate	Location	Ubicación candidata que se está evaluando

Este evento no se cancela mediante el mecanismo de Bukkit. Para rechazar un candidato, llama a:

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

Durante la precarga, CannonRTP descarta el candidato como si hubiera fallado una comprobación interna y sigue buscando. El motivo que indiques aparece en el detalle de /wc status del cañón como Rejected by another plugin: <reason> hasta que un cambio de estado posterior, como una ubicación añadida a la cola o una búsqueda agotada, lo sustituya. Al confirmar el lanzamiento, el rechazo cancela la secuencia y recupera al jugador en lugar de teletransportarlo a una ubicación que un listener ya no acepta. Los listeners permiten aplicar reglas de regiones adicionales a las de los adaptadores integrados.

Ambas emisiones se realizan en el hilo principal. Hay un intento global de precarga por tick, repartido por turnos entre los cañones activos. Mantén el manejador rápido.

CannonRTPLandingEvent

Se emite después de teletransportar al jugador y completar toda la secuencia: ya se ha ejecutado LANDING, retirado el efecto de Caída lenta propio de CannonRTP y reproducido el efecto de impacto. Un efecto anterior puede restaurarse con su duración restante; se conserva cualquier efecto más reciente de otra fuente. No se puede cancelar; usa CannonRTPLaunchEvent para impedir un lanzamiento antes de que ocurra.

Propiedad	Tipo	Descripción
player	Player	Jugador que acaba de aterrizar
cannonId	String	ID de configuración del cañón que lo ha lanzado
cannonDisplayName	String	Campo displayName del cañón
destination	Location	Copia del destino al que se envió al jugador

Sirve para conceder recompensas en la primera llegada, activar efectos posteriores, conceder permisos de regiones, anunciar llegadas o recopilar estadísticas.

Hilos y ciclo de vida

• Los tres eventos se emiten en el hilo principal.
• CannonRTPLocationValidationEvent se emite durante el tick global de precarga, con un intento por tick repartido por turnos entre los cañones activos. Un listener costoso ralentiza visiblemente la carga de las colas. Se emite una vez más por lanzamiento, al confirmar y revalidar el destino consumido de la cola.
• CannonRTPLaunchEvent se emite inmediatamente antes de construir una LaunchSequence, por lo que cualquier estado modificado, como efectos de poción, inventario o modo de juego, se aplica antes de comenzar la búsqueda.
• CannonRTPLandingEvent se emite una vez por lanzamiento, en el tick de la fase LANDING y después del efecto de impacto.

Utilidad de comprobación de protección

La clase principal del plugin también expone la comprobación de protección que usa /wc probe:

boolean allowed = CannonRTP.getInstance().isPotentialLandingLocationAllowed(location);

Devuelve true cuando todas las integraciones de protección habilitadas permiten la ubicación, según failOpenOnProtectionErrors. No comprueba el terreno, la columna de descenso, el borde del mundo ni los listeners de CannonRTPLocationValidationEvent. Devuelve false hasta que CannonRTP haya cargado sus cañones durante el arranque. CannonRTP es com.magmaguy.cannonrtp.CannonRTP.

Trabajar con cannonId

cannonId es el mismo ID que usan todos los comandos de administración, como /wc place y /wc target, y coincide con el nombre del archivo de configuración sin .yml. Una misma configuración puede controlar varias colocaciones en el mundo; todas comparten cannonId y cannonDisplayName. Para obtener la colocación exacta, usa cannonLocation de CannonRTPLaunchEvent.