API CannonRTP

La référence Java générée permet de rechercher les classes, méthodes et signatures. La version des sources et le commit utilisés sont indiqués pour chaque module.

CannonRTP expose trois événements Bukkit auxquels les autres plugins peuvent s'abonner. Ils se trouvent tous dans le package com.magmaguy.cannonrtp.api et sont déclenchés sur le thread principal du serveur.

Pour les écouter, enregistrez un @EventHandler Bukkit ordinaire ; aucune autre étape d'enregistrement n'est nécessaire.

CannonRTPLaunchEvent

Cet événement est déclenché lorsqu'un joueur s'apprête à commencer une séquence de lancement, avant l'application des effets et des éléments visuels. Il est annulable.

Propriété	Type	Description
player	Player	Joueur ayant déclenché le canon
cannonId	String	Identifiant de configuration du canon, soit le nom du fichier sans .yml
cannonDisplayName	String	Champ displayName du canon
cannonLocation	Location	Placement exact qui a été déclenché
destination	Location	Emplacement d'atterrissage sûr, déjà 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 redéclencher à chaque tick de détection un événement systématiquement annulé, CannonRTP espace les tentatives de 1 à 30 secondes tant que le joueur reste dans la zone de déclenchement. Quitter cette zone ou terminer un lancement accepté réinitialise cet espacement. Cet événement permet notamment d'appliquer des interdictions par région, des délais de récupération externes, des conditions économiques ou des vérifications de régions PvP.

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

CannonRTPLocationValidationEvent

Cet événement est déclenché pour chaque emplacement d'atterrissage candidat pendant la recherche de préchargement, puis à nouveau pour la destination utilisée lors de sa validation finale, juste avant la téléportation de largage. Pendant le préchargement, il intervient après les vérifications de la bordure du monde, de la surface, des matériaux dangereux et des protections. Lors de la validation finale du lancement, la référence actuelle du monde, la colonne d'atterrissage et les intégrations de protection sont vérifiées de nouveau avant l'événement. Cette dernière étape ne répète pas la vérification de la bordure du monde.

Propriété	Type	Description
cannonId	String	Identifiant de configuration du canon qui effectue la recherche
cannonDisplayName	String	Champ displayName du canon
candidate	Location	Emplacement d'atterrissage candidat examiné

Cet événement n'est pas annulable au sens de 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. Le motif transmis apparaît dans le détail /wc status du canon sous la forme Rejected by another plugin: <reason>, jusqu'à ce qu'un changement d'état ultérieur, comme un emplacement mis en file ou une recherche épuisée, le remplace. Lors de la validation finale, un rejet annule au contraire le lancement et récupère le joueur, au lieu de le téléporter vers une destination qu'un écouteur n'accepte plus. Les écouteurs peuvent appliquer des règles de région personnalisées en complément des adaptateurs de protection intégrés.

Remarque : les deux déclenchements se font sur le thread principal. Les tentatives de préchargement s'exécutent globalement à raison d'une par tick, en alternant les canons actifs. Gardez donc votre gestionnaire rapide.

CannonRTPLandingEvent

Cet événement est déclenché après la téléportation du joueur à destination, une fois la séquence de lancement entièrement terminée : la phase LANDING s'est exécutée, CannonRTP a retiré son propre effet Chute lente et l'effet d'impact a été joué. Un effet préexistant peut être restauré avec sa durée restante ; un effet plus récent provenant d'une autre source est conservé. Il n'est pas annulable ; utilisez CannonRTPLaunchEvent pour refuser un lancement avant son exécution.

Propriété	Type	Description
player	Player	Joueur qui vient d'atterrir
cannonId	String	Identifiant de configuration du canon qui l'a lancé
cannonDisplayName	String	Champ displayName du canon
destination	Location	Copie de la destination vers laquelle le joueur a été envoyé

Il peut servir à récompenser une première arrivée, déclencher d'autres effets, accorder des permissions de région, annoncer les arrivées ou recueillir des statistiques.

Threads et cycle de vie

• Les trois événements sont déclenchés sur le thread principal.
• CannonRTPLocationValidationEvent est déclenché pendant le tick global de préchargement, à raison d'une tentative par tick du serveur, en alternant les canons actifs. Un traitement lourd dans les écouteurs ralentit donc sensiblement le remplissage des files des canons. Il est déclenché une fois supplémentaire par lancement, lors de la validation finale de la destination mise en file.
• CannonRTPLaunchEvent est déclenché juste avant la construction d'une LaunchSequence. Les changements d'état que vous effectuez, comme les effets de potion, l'inventaire ou le mode de jeu, prennent donc effet avant le début de la phase de recherche.
• CannonRTPLandingEvent est déclenché une fois par lancement, pendant le tick de la phase LANDING, après l'effet d'impact.

Utilitaire de vérification des protections

La classe principale du plugin expose aussi la vérification des protections utilisée par /wc probe :

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

Elle renvoie true lorsque toutes les intégrations de protection activées autorisent l'emplacement, selon failOpenOnProtectionErrors. Elle ne vérifie ni le terrain, ni la colonne de largage, ni la bordure du monde, ni les écouteurs de CannonRTPLocationValidationEvent. Elle renvoie false tant que CannonRTP n'a pas chargé ses canons au démarrage. CannonRTP correspond à com.magmaguy.cannonrtp.CannonRTP.

Utiliser cannonId

cannonId est l'identifiant utilisé par toutes les commandes d'administration, comme /wc place ou /wc target. Il correspond au nom du fichier de configuration du canon sans .yml. Une même configuration peut être utilisée par plusieurs placements dans le monde ; tous partagent alors le même cannonId et le même cannonDisplayName. Pour connaître le placement exact, utilisez cannonLocation dans CannonRTPLaunchEvent.