API de CannonRTP

CannonRTP expose trois événements Bukkit permettant à d'autres plugins de s'y connecter. Tous les événements résident dans le package com.magmaguy.cannonrtp.api et sont déclenchés sur le thread principal du serveur.

Pour écouter, enregistrez un @EventHandler Bukkit normal -- il n'y a pas d'étape d'enregistrement séparée.

CannonRTPLaunchEvent

Déclenché au moment où un joueur est sur le point de commencer une séquence de lancement de canon, avant que tout visuel ou effet ne soit appliqué. Annulable.

Propriété	Type	Description
player	Player	Le joueur qui a déclenché le canon
cannonId	String	L'identifiant de configuration (nom de fichier sans .yml) du canon
cannonDisplayName	String	Le champ displayName du canon
cannonLocation	Location	Le placement exact qui a été déclenché
destination	Location	L'emplacement d'atterrissage sûr pré-validé choisi pour ce lancement

Annuler l'événement interrompt entièrement le lancement : le joueur reste sur place, aucun effet n'est appliqué, aucun délai de récupération intégré ne démarre et la destination est remise en tête de la file du canon. Pour éviter de déclencher à chaque tick de balayage des joueurs un événement systématiquement annulé, CannonRTP espace les nouvelles tentatives de 1 seconde jusqu'à 30 secondes tant que ce joueur reste dans le déclencheur ; quitter le déclencheur ou terminer un lancement accepté réinitialise cet espacement. Utile pour les listes noires basées sur les régions, les plugins de temps de recharge, les verrous économiques ou les vérifications de régions PvP.

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

CannonRTPLocationValidationEvent

Déclenché pour chaque emplacement d'atterrissage candidat lorsque CannonRTP le valide pendant la recherche de préchargement, et déclenché à nouveau pour la destination consommée lorsqu'un lancement la revalide au moment de la validation finale (juste avant la téléportation de largage). Déclenché uniquement après que toutes les vérifications intégrées (limites du monde, surface, matériaux dangereux, intégrations de protection) soient passées.

Propriété	Type	Description
cannonId	String	L'identifiant de configuration du canon effectuant la recherche
cannonDisplayName	String	Le champ displayName du canon
candidate	Location	L'emplacement d'atterrissage candidat considéré

Cet événement n'est pas annulable au sens Bukkit. Pour rejeter un candidat, appelez :

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

Pendant le préchargement, CannonRTP écarte alors le candidat comme s'il avait échoué à une vérification interne et poursuit la recherche. Au moment de la validation finale, un rejet annule au contraire le lancement et récupère le joueur plutôt que de le téléporter vers un emplacement qu'un listener n'accepte plus. Les listeners peuvent implémenter des règles de région personnalisées au-delà des adaptateurs de protection intégrés.

Remarque : les deux déclenchements ont lieu sur le thread principal, et les tentatives de préchargement s'exécutent à raison d'une par tick globalement, en tourniquet entre les canons actifs. Gardez le gestionnaire rapide.

CannonRTPLandingEvent

Déclenché après qu'un joueur ait été téléporté à la destination et que la séquence de lancement soit entièrement terminée (la phase LANDING s'est exécutée, Chute Lente a été retirée et l'explosion d'impact a été jouée). Non annulable -- utilisez CannonRTPLaunchEvent pour rejeter un lancement avant qu'il ne se produise.

Propriété	Type	Description
player	Player	Le joueur qui vient d'atterrir
cannonId	String	L'identifiant de configuration du canon qui l'a lancé
cannonDisplayName	String	Le champ displayName du canon
destination	Location	Une copie de la destination où il a été envoyé

Utile pour attribuer des récompenses à la première arrivée, déclencher des effets de suivi, accorder des permissions de région, diffuser les arrivées ou faire de l'analytique.

Threading et Cycle de Vie

• Les trois événements sont dispatchés sur le thread principal.
• CannonRTPLocationValidationEvent est dispatché pendant le tick global de préchargement (une tentative par tick de serveur, en tourniquet entre les canons actifs), donc un traitement lourd dans les listeners ralentira visiblement la vitesse à laquelle les canons chargent leurs files. Il est dispatché une fois de plus par lancement, au moment de la validation finale, lorsque la destination en file est revalidée.
• CannonRTPLaunchEvent est dispatché immédiatement avant la construction d'une LaunchSequence, donc tout état que vous modifiez (effets de potion, inventaire, mode de jeu) prend effet avant le début de la phase de recherche.
• CannonRTPLandingEvent est dispatché une fois par lancement, au tick de la phase LANDING, après l'explosion d'impact.

Travailler avec cannonId

cannonId est le même identifiant utilisé par chaque commande administrateur (/wc place, /wc target, etc.) et correspond au nom de fichier de la configuration du canon sans .yml. Notez qu'une seule configuration de canon peut piloter plusieurs placements en jeu ; tous partagent le même cannonId et cannonDisplayName. Si vous avez besoin du placement exact, utilisez cannonLocation depuis CannonRTPLaunchEvent.