CannonRTP-API

Die generierte Java-Referenz bietet durchsuchbare Klassen, Methoden und Signaturen. Für jedes Modul sind Quellversion und Commit angegeben.

CannonRTP stellt drei Bukkit-Events bereit, in die sich andere Plugins einklinken können. Alle Events liegen im Paket com.magmaguy.cannonrtp.api und werden im Haupt-Server-Thread gefeuert.

Zum Mithören registriere einen normalen Bukkit-@EventHandler -- es gibt keinen separaten Registrierungsschritt.

CannonRTPLaunchEvent

Wird in dem Moment gefeuert, in dem ein Spieler im Begriff ist, eine Kanonenstartsequenz zu beginnen, bevor irgendwelche Visuals oder Effekte angewendet werden. Abbrechbar.

Eigenschaft	Typ	Beschreibung
player	Player	Der Spieler, der die Kanone ausgelöst hat
cannonId	String	Die Konfigurations-ID (Dateiname ohne .yml) der Kanone
cannonDisplayName	String	Das Feld displayName der Kanone
cannonLocation	Location	Die genaue Platzierung, die ausgelöst wurde
destination	Location	Der vorab validierte sichere Landeort, der für diesen Start gewählt wurde

Das Abbrechen des Events bricht den Start komplett ab: Der Spieler bleibt, wo er ist, es werden keine Effekte angewendet, es startet keine eingebaute Start-Abklingzeit, und das Ziel wird an den Anfang der Kanonenwarteschlange zurückgegeben. Damit nicht bei jedem Spieler-Scan-Tick ein dauerhaft abgebrochenes Event gefeuert wird, staffelt CannonRTP die Wiederholungen von 1 Sekunde bis auf 30 Sekunden hoch, solange dieser Spieler im Auslöser bleibt; das Verlassen des Auslösers oder ein abgeschlossener angenommener Start setzt die Staffelung zurück. Nützlich für regionsbasierte Blacklists, Cooldown-Plugins, Economy-Sperren oder PvP-Regionsprüfungen.

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

CannonRTPLocationValidationEvent

Wird während der Vorlade-Suche für jeden möglichen Landeort ausgelöst, den CannonRTP validiert, und erneut für das entnommene Ziel bei der abschließenden Validierung des Starts, unmittelbar vor der Abwurf-Teleportation. Beim Vorladen erfolgt dies nach bestandenen Prüfungen auf Weltgrenze, Oberfläche, unsichere Materialien und Schutz. Beim Abschluss des Starts werden die aktuelle Weltreferenz, die Blocksäule am Landeort und die Schutzintegrationen vor dem Event erneut geprüft. Die Weltgrenzenprüfung wird dabei nicht wiederholt.

Eigenschaft	Typ	Beschreibung
cannonId	String	Die Konfigurations-ID der suchenden Kanone
cannonDisplayName	String	Das Feld displayName der Kanone
candidate	Location	Der Kandidaten-Landeort, der in Betracht gezogen wird

Dieses Event ist im Bukkit-Sinne nicht abbrechbar. Um einen Kandidaten zu verwerfen, rufe auf:

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

Während des Vorladens verwirft CannonRTP den Kandidaten dann, als hätte er eine interne Prüfung nicht bestanden, und setzt die Suche fort. Der übergebene Grund erscheint im /wc status-Detail der Kanone als Rejected by another plugin: <reason>, bis eine spätere Statusänderung ihn ersetzt, etwa ein in die Warteschlange gestellter Ort oder eine erschöpfte Suche. Zum Festlegungszeitpunkt bricht ein Verwerfen stattdessen den Start ab und rettet den Spieler, statt ihn an einen Ort zu teleportieren, den ein Listener nicht mehr akzeptiert. Listener können benutzerdefinierte Regionsregeln über die integrierten Schutzadapter hinaus implementieren.

Hinweis: Beide Auslösungen erfolgen im Haupt-Thread, und Vorladeversuche laufen global einer pro Tick, im Round-Robin über aktive Kanonen. Halte den Handler schnell.

CannonRTPLandingEvent

Wird ausgelöst, nachdem ein Spieler zum Ziel teleportiert wurde und die Startsequenz vollständig abgeschlossen ist: Die LANDING-Phase ist gelaufen, CannonRTP hat seinen eigenen Effekt „Langsamer Fall“ entfernt und der Aufschlagseffekt wurde abgespielt. Ein zuvor bestehender Effekt kann mit seiner Restdauer wiederhergestellt werden; ein neuerer Effekt aus einer anderen Quelle bleibt erhalten. Nicht abbrechbar -- verwende CannonRTPLaunchEvent, um einen Start zu verhindern, bevor er passiert.

Eigenschaft	Typ	Beschreibung
player	Player	Der Spieler, der gerade gelandet ist
cannonId	String	Die Konfigurations-ID der Kanone, die ihn gestartet hat
cannonDisplayName	String	Das Feld displayName der Kanone
destination	Location	Eine Kopie des Ziels, zu dem er gesendet wurde

Nützlich, um Belohnungen bei der ersten Ankunft zu vergeben, Folgeeffekte auszulösen, Regionsberechtigungen zu gewähren, Ankünfte zu broadcasten oder für Analytik.

Threading und Lebenszyklus

• Alle drei Events werden im Haupt-Thread verteilt.
• CannonRTPLocationValidationEvent wird während des globalen Vorlade-Ticks verteilt (ein Versuch pro Server-Tick, Round-Robin über aktive Kanonen), daher verlangsamt schwere Arbeit in Listenern sichtbar, wie schnell Kanonen ihre Warteschlangen aufladen. Es wird pro Start noch einmal verteilt, zum Festlegungszeitpunkt, wenn das Ziel aus der Warteschlange neu validiert wird.
• CannonRTPLaunchEvent wird unmittelbar bevor eine LaunchSequence erstellt wird verteilt, sodass jeder Zustand, den du mutierst (Trankeffekte, Inventar, Spielmodus), vor Beginn der Suchphase wirksam wird.
• CannonRTPLandingEvent wird einmal pro Start verteilt, im LANDING-Phasen-Tick, nach dem Aufschlagsausbruch.

Hilfsmethode für die Schutzprüfung

Die Hauptklasse des Plugins stellt außerdem die Schutzprüfung bereit, die /wc probe verwendet:

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

Sie gibt true zurück, wenn jede aktivierte Schutzintegration den Ort erlaubt, und folgt dabei failOpenOnProtectionErrors. Gelände, die Airdrop-Säule, die Weltgrenze und Listener von CannonRTPLocationValidationEvent prüft sie nicht. Bis CannonRTP beim Start seine Kanonen geladen hat, gibt sie false zurück. CannonRTP ist com.magmaguy.cannonrtp.CannonRTP.

Arbeiten mit cannonId

cannonId ist dieselbe ID, die von jedem Admin-Befehl (/wc place, /wc target, etc.) verwendet wird und entspricht dem Dateinamen der Kanonenkonfiguration ohne .yml. Beachte, dass eine einzelne Kanonenkonfiguration viele Platzierungen in der Welt steuern kann; alle teilen sich dieselbe cannonId und cannonDisplayName. Wenn du die genaue Platzierung benötigst, verwende cannonLocation aus CannonRTPLaunchEvent.