CannonRTP (WorldCannon)

CannonRTP is a multi-cannon random-teleportation plugin for Minecraft servers. "WorldCannon" is an older / wiki-section name; the plugin registers as CannonRTP in Bukkit, ships as CannonRTP.jar, and that is the name players and admins see.

Key naming details:

• Plugin name: CannonRTP
• Root command: /cannonrtp
• Aliases: /crtp, /wc
• Permissions: cannonrtp.admin, cannonrtp.use
• Config folder: plugins/CannonRTP/

What It Does

CannonRTP is a multi-cannon random-landing system rather than a single fixed launcher. Each configured cannon can be placed at one or many locations in the world, and each placement watches for players walking into its trigger radius.

Each cannon can:

• be placed multiple times via /wc create and /wc place -- a single cannon config drives every placement
• watch for players entering a per-cannon trigger radius (default 1.75 blocks)
• preload and maintain a queue of safe landing locations in a configured target world (cross-world targeting is supported)
• reject unsafe terrain, blocked spaces, protected land, and locations outside the world border
• optionally require an extra per-cannon permission
• launch players through a five-phase cinematic sequence
• display a FreeMinecraftModels 3D animated cannon (per-cannon customModel or via a global priority list); falls back to color-shifting orbit particles when FMM is not installed
• show a billboarded floating status label above the cannon (Ready / Charging / Maintaining / Exhausted / Disabled)

Launch Flow

Before using a cannon, generate or explore the target world's configured search area. CannonRTP loads existing chunks without generating terrain, so an unexplored search radius may not provide any destinations.

The launch sequence is driven by a five-phase state machine (SEARCHING -> FIRING -> TELEPORTING -> DROPPING -> LANDING). When a player walks into an eligible cannon's trigger radius:

1. CannonRTP checks cannonrtp.use.
2. It checks the cannon's optional requiredPermission.
3. It checks the per-player launch cooldown (runtime.launchCooldownSeconds, default 30 seconds). The gate applies across all cannons and does not consume a queued destination.
4. It verifies the cannon has at least one preloaded landing location queued. (Disabled cannons, cannons in an unloaded world, and cannons in an unloaded chunk never reach this point -- they are excluded from the tick loop entirely, so they cannot be triggered at all.)
5. It consumes one preloaded safe landing location from that cannon's queue.
6. It fires CannonRTPLaunchEvent (cancellable). If a listener cancels it, the destination is returned to the queue and no cooldown starts.
7. Searching phase (default 42 ticks, configurable via launchWarmupTicks): the player gets Levitation, the cannon plays its fire animation if a custom model is active, and randomized coordinate previews flicker through title/subtitle. While a model is active the player also gets Invisibility so the animation reads cleanly.
8. Firing phase (default 45 ticks via verticalBoostTicks): Levitation/Invisibility are removed, the blast-off sound plays, a flame+smoke+explosion burst spawns, and verticalBoostVelocity is applied each tick. The true destination coordinates are revealed.
9. Teleporting phase (single tick): the queued destination is revalidated (terrain column, protection integrations, API listeners). If it still passes, the player is teleported exactly 50 blocks above it and Slow Falling is applied. The airdrop height is never clamped -- the landing validator already guarantees the arrival block sits below the world's maximum height, and a destination that no longer validates cancels the launch and recovers the player instead.
10. Dropping phase: the player drifts down with a smoke trail (LARGE_SMOKE + CAMPFIRE_SIGNAL_SMOKE).
11. Landing phase: entered as soon as the player touches the ground. Slow Falling is removed, an impact burst plays (cloud shockwave, flame ring, dust transition), and CannonRTPLandingEvent fires. If the drop instead runs past its maximum duration (slowFallingSeconds x 20 ticks), CannonRTP recovers the player and no landing event is emitted.

Landing Safety Rules

Before a location is accepted into the preload queue, the current code checks, in order:

• the target world is loaded (while it is not, the cannon stops preloading and reports Target world <name> is not loaded.)
• the search center resolves -- the configured searchCenter, else the cannon's own location when it is in the target world, else the target world's spawn
• the candidate is inside the world border
• the candidate chunk is loaded (loaded on demand without generating)
• a highest non-air block exists at the candidate column
• the surface block directly below the landing spot is solid and non-liquid
• that surface block is not in the configured unsafe ground materials list, and is not the Nether bedrock roof
• the landing spot is at or above the world's minimum height, and the arrival block 51 blocks above it stays below the world's maximum height
• every block of the 52-block airdrop column (landing spot up through the arrival head block) is air or passable
• no block in that column is in the configured unsafe body materials list
• all enabled protection plugin integrations allow the location
• any CannonRTPLocationValidationEvent listener does not veto the candidate

In the Nether, CannonRTP rejects the bedrock roof and scans downward for an exposed cavern floor whose complete airdrop column is safe. This allows Nether targets without dropping the player above the ceiling or through solid terrain.

Search attempts are globally rate-limited to one per tick (20/sec), shared fairly across all active cannons via round-robin. Each cannon has its own timeout counter (searchTimeoutAttempts, default 100, minimum 10).

Cannon States

Each cannon has an internal state visible via /wc status or /wc list:

Display	Internal State	Meaning
Disabled	--	The cannon is explicitly disabled in its config
Charging	SEARCHING (queue empty)	Still preloading its first batch of safe locations
Maintaining	SEARCHING (queue not empty)	Has some locations but is still refilling consumed slots
Ready	READY	Has enough preloaded locations (>= chargedLocationsPerCannon) to launch players
Exhausted	EXHAUSTED	Burned through searchTimeoutAttempts without filling the reserve

The internal search state is one of exactly three values (READY, SEARCHING, EXHAUSTED); Disabled is decided before it is consulted, and Charging / Maintaining are the two renderings of SEARCHING. Ready wins over Exhausted -- a cannon that still holds its charged reserve reads as Ready even if its last search window timed out.

There is no separate "invalid configuration" state. When a cannon's targetWorld cannot be resolved, the cannon keeps its current search-state label and the $reason column of /wc status becomes Target world <name> is not loaded. (The statusLabels.invalid message key exists in messages.yml but nothing renders it in the current build.)

A cannon will launch players as soon as it has at least one queued destination. The chargedLocationsPerCannon threshold only affects the visual READY label.

Runtime Expectations

• Minecraft: plugin.yml declares api-version: 1.21.4; the current source tree is built against the Spigot 26.2-R0.1-SNAPSHOT API
• Java: 21
• Recommended server software: Paper or a current compatible fork
• MagmaCore: 2.2.0 or newer (shared library, shaded into the plugin)
• Optional dependency: FreeMinecraftModels (for 3D animated cannon models)

Resilience

CannonRTP keeps its visuals and queues consistent across world and chunk lifecycle events:

• when a cannon's chunk unloads, its label and model are despawned; they respawn on chunk reload
• when a cannon's world unloads, the cannon is suspended; it wakes up if the world is loaded again
• when FreeMinecraftModels is enabled or disabled mid-session, the model cache is invalidated and visuals refresh on the next tick
• before the airdrop teleport, the queued destination is rechecked against terrain, protection integrations, and API listeners; if it became unsafe, the launch recovers the player instead of committing to stale coordinates
• launch cleanup removes only the Levitation, Invisibility, and Slow Falling effects CannonRTP still owns, and restores any older effect it temporarily replaced instead of deleting another plugin's newer state
• if a launch cannot continue because its destination world unloads, CannonRTP recovers the player to the cannon seat or another loaded-world spawn and keeps Slow Falling when no safe recovery world is available

Start Here

• Commands and Permissions
• Configuration
• Content Packages
• Messages and Titles
• Protection Integrations
• API Events