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, and the destination is returned to the head of the cannon's queue for reuse on the next launch. 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. 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");

CannonRTP will then discard the candidate as if it had failed an internal check and continue searching. Listeners can implement custom region rules beyond the built-in protection adapters.

Note: fired on the main thread during preload attempts (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.
• 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.