CannonRTP API

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). Fires only after all built-in checks (world border, surface, unsafe materials, protection integrations) pass.

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. 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, Slow Falling has been removed, and the impact burst has played). 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.

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.