CannonRTP API

Generated Java reference includes searchable classes, methods and signatures, with the source version and commit recorded for each module.

CannonRTP exposes three Bukkit events for other plugins to hook into. All events live in the com.magmaguy.cannonrtp.api package and are fired on the main server thread.

To listen, register a normal Bukkit @EventHandler -- there is no separate registration step.

CannonRTPLaunchEvent

Fired the moment a player is about to begin a cannon launch sequence, before any visuals or effects are applied. Cancellable.

Property	Type	Description
player	Player	The player who triggered the cannon
cannonId	String	The config id (filename without .yml) of the cannon
cannonDisplayName	String	The cannon's displayName field
cannonLocation	Location	The exact placement that was triggered
destination	Location	The pre-validated safe landing location chosen for this launch

Cancelling the event aborts the launch entirely: the player stays where they are, no effects are applied, no built-in launch cooldown starts, and the destination is returned to the head of the cannon's queue. To avoid firing a persistently cancelled event every player-scan tick, CannonRTP backs retries off from 1 second up to 30 seconds while that player remains inside the trigger; leaving the trigger or completing an accepted launch clears the backoff. Useful for region-based blacklists, cooldown plugins, economy gates, or PvP region checks.

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

CannonRTPLocationValidationEvent

Fired for each candidate landing location as CannonRTP validates it during the preload search, and fired again for the consumed destination when a launch revalidates it at commit time (just before the airdrop teleport). During preload, it fires after the world-border, surface, unsafe-material and protection checks pass. At launch commit, the current world reference, landing column and protection integrations are checked again before the event. The commit path does not repeat the world-border check.

Property	Type	Description
cannonId	String	The config id of the cannon doing the search
cannonDisplayName	String	The cannon's displayName field
candidate	Location	The candidate landing location being considered

This event is not cancellable in the Bukkit sense. To veto a candidate, call:

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

During preload, CannonRTP then discards the candidate as if it had failed an internal check and continues searching. The reason you pass appears in the cannon's /wc status detail as Rejected by another plugin: <reason> until a later status change, such as a queued location or an exhausted search, replaces it. At commit time, rejecting instead cancels the launch and recovers the player rather than teleporting them to a location a listener no longer accepts. Listeners can implement custom region rules beyond the built-in protection adapters.

Note: both dispatches happen on the main thread, and preload attempts run one per tick globally, round-robin across active cannons. Keep the handler fast.

CannonRTPLandingEvent

Fired after a player has been teleported to the destination and the launch sequence has fully completed (the LANDING phase has run, CannonRTP has released its own Slow Falling effect, and the impact burst has played). A pre-existing effect can be restored with its remaining duration; a newer effect from another source is left alone. Non-cancellable -- use CannonRTPLaunchEvent to veto a launch before it happens.

Property	Type	Description
player	Player	The player who just landed
cannonId	String	The config id of the cannon that launched them
cannonDisplayName	String	The cannon's displayName field
destination	Location	A copy of the destination they were sent to

Useful for awarding rewards on first arrival, triggering follow-up effects, granting region permissions, broadcasting arrivals, or analytics.

Threading and Lifecycle

• All three events are dispatched on the main thread.
• CannonRTPLocationValidationEvent is dispatched during the global preload tick (one attempt per server tick, round-robin across active cannons), so heavy work in listeners will visibly slow down how quickly cannons charge their queues. It is dispatched once more per launch, at commit time, when the queued destination is revalidated.
• CannonRTPLaunchEvent is dispatched immediately before a LaunchSequence is constructed, so any state you mutate (potion effects, inventory, gamemode) takes effect before the searching phase begins.
• CannonRTPLandingEvent is dispatched once per launch, in the LANDING phase tick, after the impact burst.

Protection Check Helper

The main plugin class also exposes the protection check that /wc probe uses:

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

It returns true when every enabled protection integration allows the location, following failOpenOnProtectionErrors. It does not check terrain, the airdrop column, the world border, or CannonRTPLocationValidationEvent listeners. It returns false until CannonRTP has loaded its cannons during startup. CannonRTP is com.magmaguy.cannonrtp.CannonRTP.

Working with cannonId

cannonId is the same id used by every admin command (/wc place, /wc target, etc.) and matches the filename of the cannon config without .yml. Note that a single cannon config may drive many in-world placements; all of them share the same cannonId and cannonDisplayName. If you need the exact placement, use cannonLocation from CannonRTPLaunchEvent.