Skip to main content

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); a disabled cannon spawns no label or model and shows as Disabled only in /wc list and /wc status

Quick Start​

  1. Put CannonRTP.jar in plugins/ and start the server.
  2. Run /wc initialize in-game, then /wc setup to download the cannon model packs. Downloads need a linked Nightbreak account, and the models need FreeMinecraftModels. Without models, cannons use particle visuals.
  3. Stand where the cannon should be and run /wc create spawn. The new cannon lands players in the world it stands in.
  4. Optional: run /wc target spawn <world> to land players in another loaded world, or /wc center spawn to search around your current position.
  5. Make sure the search area exists as generated terrain (500 to 5000 blocks from the search center by default), then run /wc status. The cannon launches players once it holds at least one checked destination.

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 when the player is on the ground and their vertical speed is below 0.08 blocks per tick. CannonRTP releases its own Slow Falling effect, 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:

DisplayInternal StateMeaning
Disabled--The cannon is explicitly disabled in its config
ChargingSEARCHING (queue empty)Still preloading its first batch of safe locations
MaintainingSEARCHING (queue not empty)Has some locations but is still refilling consumed slots
ReadyREADYHas enough preloaded locations (>= chargedLocationsPerCannon) to launch players
ExhaustedEXHAUSTEDBurned 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.

A cannon also shows Exhausted without sampling any terrain when an enabled protection plugin's integration failed to load and failOpenOnProtectionErrors is false. See Protection Integrations.

There is no separate "invalid configuration" state. When a cannon's target world becomes unavailable, destinations for that world are discarded and the search state resets to SEARCHING. An empty queue displays Charging, and the $reason column of /wc status reports Target world <name> is not loaded. Search resumes when the target world loads. The statusLabels.invalid key exists in messages.yml but is not rendered.

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.3-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)
  • Metrics: CannonRTP reports anonymous usage statistics to bStats (plugin id 34460). To opt out, set enabled: false in plugins/bStats/config.yml, which applies to every plugin on the server that uses bStats.

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, disabled, or finishes a content reload on a version with the reload-complete event, stale cannon models are discarded and recreated from the current model registry; removed model instances are also detected directly on older FMM versions without that event
  • 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
  • /wc reload, a restart-free plugin update, and every cannon-editing command (create, place, remove, delete, target, center) rebuild all cannons: active launches are cancelled with the player recovered to the cannon seat, queued destinations are discarded and searched again, and launch cooldowns reset
  • if a player disconnects mid-launch, the launch ends and CannonRTP removes the effects it applied; the player is not teleported

Troubleshooting​

  • A cannon stays Charging or turns Exhausted. Run /wc status and read its reason. Common causes are an unloaded target world, a search area that was never generated, surfaces that fail the landing safety rules (water is an unsafe material by default, so open ocean never qualifies), and claims or regions covering the area. /wc probe tests the protection checks where you stand. An enabled protection integration that failed to load stops every cannon from searching; see Protection Integrations.
  • Players walk into a cannon and nothing happens. Check cannonrtp.use, the cannon's requiredPermission, whether the cannon is enabled, and the launch cooldown (runtime.launchCooldownSeconds, 30 seconds by default).
  • Before deleting a cannon or moving a live destination, back up its file in plugins/CannonRTP/cannons/.

When asking for help, include the /wc status output, the CannonRTP and server versions, the affected cannon's config file and the full server log. /logify uploads the log and returns a link.

Start Here​