CannonRTP Configuration

CannonRTP uses one global config file plus one config file per cannon.

File Layout

• Global config: plugins/CannonRTP/config.yml
• Per-cannon configs: plugins/CannonRTP/cannons/<id>.yml

The plugin also ships an example cannon package named example_world_cannon. It is enabled by default and places itself at the first world's spawn.

Global Config Structure

The main config is organized under:

• runtime.*
• landing.*
• messages.*
• protection.*

Runtime Settings

Key	Default	Behavior
runtime.particleIntervalTicks	15	How often idle cannon particles render (minimum 5)
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Priority list of FreeMinecraftModels model names, checked top to bottom. The first model found on the server is used for any cannon that does not set its own customModel. If none are found, particles are used instead.

Landing Search Settings

Key	Default	Behavior
landing.searchAttemptsPerTick	2	Search attempts per cannon per tick while preloading (minimum 1)
landing.preloadedLocationsPerCannon	10	Total number of safe destinations the plugin tries to keep queued per cannon (minimum 1)
landing.chargedLocationsPerCannon	5	How many locations a cannon must have before it is considered charged and launch-ready (minimum 1, capped at preloadedLocationsPerCannon)
landing.searchTimeoutSeconds	1000	Time in seconds before a still-searching cannon is marked exhausted (minimum 10)
landing.slowFallingSeconds	60	Slow Falling duration after arrival in seconds; the effect is removed early when the player lands (minimum 1)
landing.failOpenOnProtectionErrors	false	If a protection API errors, block the landing by default

Landing Sounds

The following sound keys are configurable:

• landing.sounds.levitationStart.sound (default: BLOCK_BEACON_ACTIVATE)
• landing.sounds.levitationStart.volume (default: 1.0)
• landing.sounds.levitationStart.pitch (default: 1.15)
• landing.sounds.blastOff.sound (default: ENTITY_GENERIC_EXPLODE)
• landing.sounds.blastOff.volume (default: 1.0)
• landing.sounds.blastOff.pitch (default: 0.9)

Sound values use Bukkit Sound registry names or namespaced keys. Invalid sound names are logged as warnings and the sound is silently skipped.

Unsafe Material Lists

CannonRTP rejects candidate landing spots based on two material lists:

• landing.unsafeGroundMaterials -- blocks that should never be stood on
• landing.unsafeBodyMaterials -- blocks that should never occupy the feet or head space

Default unsafe ground materials:

• LAVA
• MAGMA_BLOCK
• CAMPFIRE
• SOUL_CAMPFIRE
• CACTUS
• POWDER_SNOW

Default unsafe body materials:

• LAVA
• WATER
• FIRE
• SOUL_FIRE
• SWEET_BERRY_BUSH
• POWDER_SNOW
• COBWEB

Message Settings

All messages support MagmaCore gradients, MiniMessage tags, and legacy color codes. The $prefix placeholder is replaced with the configured prefix value.

The plugin exposes message keys under:

Key	Placeholders	Description
messages.prefix	--	Prefix used by all CannonRTP messages
messages.helpHeader	$prefix	Header shown by /cannonrtp
messages.createdCannon	$prefix, $cannon, $id, $path	Sent after creating a cannon
messages.deletedCannon	$prefix, $cannon	Sent after deleting a cannon
messages.movedCannon	$prefix, $cannon	Sent after moving a cannon
messages.targetWorldUpdated	$prefix, $cannon, $world	Sent after changing a cannon's target world
messages.searchCenterUpdated	$prefix, $cannon	Sent after changing a cannon's search center
messages.reload	$prefix, $count	Sent after reloading
messages.noPermission	$prefix, $cannon	Sent when a player can see a cannon but cannot use it
messages.cannonDisabled	$prefix, $cannon	Sent when a player steps into a disabled cannon
messages.queueCalibration	$prefix, $cannon, $queued, $target, $seconds	Sent while a cannon is still preloading
messages.noValidLocationYet	$prefix, $cannon	Sent when no safe location has been found yet
messages.noValidLocationFound	$prefix, $cannon, $reason	Sent when CannonRTP gives up after timing out
messages.invalidConfiguration	$prefix, $cannon, $reason	Sent when a configuration error is detected
messages.statusLine	$prefix, $cannon, $status, $queued, $target, $reason	Line format used by /wc status and /wc list
messages.probeAllowed	$prefix	Sent by /wc probe when the location is valid
messages.probeBlocked	$prefix, $plugin, $reason	Sent by /wc probe when the location is blocked
messages.unknownCommand	$prefix	Sent when an admin uses an unrecognized subcommand

Title Messages

Key	Placeholders	Description
messages.titles.launchQueuedTitle	$cannon	Title shown when a launch starts
messages.titles.launchQueuedSubtitle	$cannon	Subtitle shown when a launch starts
messages.titles.destinationPreviewTitle	$x, $y, $z	Title shown during the searching phase
messages.titles.destinationPreviewSubtitle	$x, $y, $z	Subtitle shown during the searching phase
messages.titles.destinationConfirmedTitle	$x, $y, $z, $world	Title shown at the start of the firing phase and again after teleporting
messages.titles.destinationConfirmedSubtitle	$x, $y, $z, $world	Subtitle shown at the start of the firing phase and again after teleporting
messages.titles.arrivalSubtitles	--	List of titles; one is picked at random and shown as the title after the player is dropped over the destination

The coordinate preview during the searching phase does not show the actual destination -- it shows randomized coordinates within the cannon's search area as a visual effect. The true destination is revealed only in the confirmed title at the start of the firing phase.

Per-Cannon Config Fields

Each cannon file (plugins/CannonRTP/cannons/<id>.yml) stores these fields:

Field	Default	Notes
isEnabled	true for newly created cannons	Disabled cannons do not trigger
displayName	CannonRTP (or the name provided at creation)	Used in messages, status output, and the floating label
cannonLocation	Required	Where the cannon trigger exists
targetWorld	Current world at creation time	Must be loaded at runtime
searchCenter	null (falls back to the target world's spawn)	If unset, the plugin uses the target world's spawn location
triggerRadius	1.75	Radius used to detect nearby players (minimum 0.5)
minSearchRadius	500	Minimum landing search distance from the search center (minimum 0)
maxSearchRadius	5000	Maximum landing search distance from the search center (always at least minSearchRadius + 1)
verticalBoostTicks	45	Ticks of upward velocity before teleport (minimum 0)
verticalBoostVelocity	1.35	Upward velocity applied during launch (minimum 0)
enableParticles	true	Controls idle cannon particle animation (only used when no custom model is active)
requiredPermission	blank	Optional extra permission gate for this specific cannon
customModel	blank	Optional FreeMinecraftModels model name for this specific cannon. If blank, the plugin falls back to runtime.cannonModelPriority

Cannon Creation Defaults

When you run /wc create <id>:

• the cannon id is lowercased and characters other than a-z, 0-9, _, and - are replaced with _
• the display name defaults to CannonRTP if not specified, or the provided name with underscores converted to spaces
• cannonLocation is set to your current location
• targetWorld is set to your current world
• searchCenter is not set (falls back to the target world's spawn)

After creation, the plugin prints the config file path and suggests which fields to edit manually: displayName, customModel, requiredPermission, verticalBoostTicks, and verticalBoostVelocity.

FreeMinecraftModels Integration

If a cannon resolves to a valid FreeMinecraftModels model (either through its own customModel field or the global runtime.cannonModelPriority list) and FreeMinecraftModels is installed:

• A static model entity is spawned at the cannon location
• The floating text label is raised higher to avoid overlapping the model
• Idle particle animations are suppressed while a model is active
• When a player launches, the model plays its fire animation (if one exists in the model file)

Runtime Validation Behavior

CannonRTP rejects candidate landing locations when any of these checks fail:

• the target world is unloaded
• the search center is invalid
• the random sample lands outside the world border
• no safe solid surface is found
• the feet or head space is blocked
• the terrain or body blocks match the configured unsafe material lists
• a protection integration blocks the landing

If a cannon cannot find enough valid locations before landing.searchTimeoutSeconds, it becomes exhausted and starts returning the configured failure message instead of launching players. The failure message includes a summary of the most common rejection reasons.

The cannon's search window restarts whenever it needs to refill consumed locations (e.g. after a player launches and a slot opens up).

Interaction Guard

CannonRTP prevents a player from triggering a cannon while they are already in an active launch sequence. Once the current launch finishes (landing or disconnect), the player can use a cannon again. There is no additional cooldown timer.