CannonRTP

Java reference for CannonRTP build version 1.2.9. Generated from source commit 3d2bf8c2eb60. This reference describes that checkout, not a separate release.

Integration guide · All Java APIs · Source repository

Documented public and protected declarations include implementation types. Use the integration guide to choose extension points; visibility alone does not promise API stability.

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.

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.

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.

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.

Building From Source

CannonRTP builds with JDK 21 and Maven. From the repository root, run:

mvn -Dmaven.test.skip=true package

-Dmaven.test.skip=true also skips compiling the tests, which target Java 25 and need JDK 25. The plugin JAR is written to target/CannonRTP.jar. If the MC_DIST_DIR environment variable is set, the build also copies the JAR into that folder.

MagmaCore is shaded into the JAR and comes from MagmaGuy's Maven repository. When the source needs MagmaCore changes newer than the published build, publish MagmaCore to your local Maven repository first so Maven picks up that newer snapshot, as described in Building a consumer after library changes.