CannonRTP Configuration

CannonRTP splits its global settings across several files in plugins/CannonRTP/, plus one per-cannon config file in plugins/CannonRTP/cannons/.

File Layout

File	Purpose
plugins/CannonRTP/config.yml	Top-level runtime flags (setup state, language, particle interval, cannon model priority, Spigot resource id, Nightbreak auto-update toggle)
plugins/CannonRTP/landing.yml	Landing search tuning (queue size, timeout attempts, slow-fall duration, unsafe material lists, fail-open behavior)
plugins/CannonRTP/sounds.yml	Sounds played during the launch sequence
plugins/CannonRTP/messages.yml	All player-facing messages, prefixes, and title pools
plugins/CannonRTP/protection.yml	Per-plugin protection integration toggles
plugins/CannonRTP/cannons/<id>.yml	One file per cannon (each can drive multiple placements)
plugins/CannonRTP/cannons_disabled/	Holding folder for cannon configs that ship with content packages but are currently disabled. The /wc setup menu moves files between cannons/ and cannons_disabled/ when you enable or disable a content package.
plugins/CannonRTP/content_packages/<package>.yml	Generated metadata for each Nightbreak content package (version, download link, prefixes used to find its files). Not normally hand-edited.

The plugin ships three example cannon configs out of the box:

• example_cannonrtp.yml -- empty reference template (display name Example World Cannon), disabled by default. Use it as a YAML reference when hand-writing cannon files.
• cannonrtp_free_cannon.yml -- enabled, no placements, points at the free cannonrtp FMM model.
• cannonrtp_premium_cannon.yml -- enabled, no placements, points at the premium cannonrtp_premium FMM model.

None of these have cannonLocations filled in by default, so nothing spawns in the world until an admin runs /wc create or /wc place.

config.yml

Key	Default	Behavior
setupDone	false	Tracks whether the Nightbreak first-time setup has been completed
language	english	Translation file to load. Release 1 ships English-only; the key exists for future translation packs
runtime.particleIntervalTicks	15	Exact interval between idle cannon-particle renders, in server ticks (minimum 1; use 1 to render every tick)
runtime.launchCooldownSeconds	30	Seconds a player must wait between accepted cannon launches (minimum 0; use 0 to disable). Cancelled CannonRTPLaunchEvents do not start the cooldown.
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, the orbit-particle fallback is used.
runtime.spigotResourceId	""	Spigot resource id used by the version checker. Leave blank to disable.
nightbreak.autoDownloadPluginUpdates	false	Added by the shaded MagmaCore library. When true, CannonRTP automatically downloads available plugin and content update files on startup (applied after the next server restart). Automatic plugin downloads require a valid Nightbreak account token and an active supporter membership. Leave false to use the in-game update button instead.

landing.yml

Key	Default	Behavior
preloadedLocationsPerCannon	10	Total number of safe destinations the plugin tries to keep queued per cannon (minimum 1)
chargedLocationsPerCannon	1	How many locations a cannon must hold before its status label flips to Ready (minimum 1, capped at preloadedLocationsPerCannon). Cannons will launch players as soon as the queue has at least one location -- this threshold only affects the visual label.
searchTimeoutAttempts	100	How many failed search attempts before a cannon is marked Exhausted (minimum 10). Search attempts are globally rate-limited to one per tick (20 per second), shared fairly across all active cannons.
slowFallingSeconds	60	Maximum Slow Falling duration after airdrop (minimum 1). The effect is removed early when the player lands.
failOpenOnProtectionErrors	false	If a protection plugin API errors, block the landing by default. Set true to allow landings to continue when a protection plugin cannot be queried safely.
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Materials that disqualify a landing surface
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Materials that disqualify the feet or head space of a landing

Materials are Bukkit Material enum names. Invalid entries are logged as warnings and skipped.

sounds.yml

Key	Default	Behavior
levitationStart.sound	BLOCK_BEACON_ACTIVATE	Sound played when the searching phase begins
levitationStart.volume	1.0
levitationStart.pitch	1.15
blastOff.sound	ENTITY_GENERIC_EXPLODE	Sound played at the start of the firing phase
blastOff.volume	1.0
blastOff.pitch	0.9

Sound values can be Bukkit Sound enum names (e.g. BLOCK_BEACON_ACTIVATE) or namespaced keys (e.g. minecraft:block.beacon.activate). Invalid sound names are logged as warnings and the sound is silently skipped at that step.

messages.yml

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

For the full list of message keys, placeholders, and the title pools used by the launch sequence, see the Messages and Titles page.

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 and show as Disabled
displayName	CannonRTP (or the name passed at creation)	Used in messages, status output, and the floating label
cannonLocations	empty list	List of serialized world,x,y,z,pitch,yaw strings. One cannon config can spawn many in-world placements. Managed by /wc create, /wc place, /wc remove.
targetWorld	current world at creation time	Cross-world targeting is supported -- set this to land players in a different world from the cannon. Must be loaded at runtime; while it is not, the cannon stops preloading and its /wc status detail reads Target world <name> is not loaded.
searchCenter	null	If unset, the plugin radiates from the cannon's own location (when the cannon is in the target world) or from the target world's spawn
triggerRadius	1.75	Radius around the cannon used to detect nearby players (minimum 0.5 blocks)
minSearchRadius	500	Minimum landing search distance from the search center (minimum 0)
maxSearchRadius	5000	Maximum landing search distance (always clamped to at least minSearchRadius + 1)
launchWarmupTicks	42	Length of the Searching phase in ticks (minimum 1)
verticalBoostTicks	45	Length of the Firing phase in ticks (minimum 0)
verticalBoostVelocity	1.35	Upward velocity applied every tick of the firing phase (minimum 0)
enableParticles	true	Controls the idle orbit-particle animation. Only rendered when no custom model is active and a player is within 36 blocks.
requiredPermission	""	Optional extra permission gate for this specific cannon. Players with cannonrtp.use but without this node see the configured no-permission message.
customModel	""	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, _, - are replaced with _
• displayName defaults to CannonRTP unless /wc create <id> <display_name> was used (underscores in <display_name> are converted to spaces)
• the player's current location is appended to cannonLocations
• targetWorld is set to the player's current world
• searchCenter is not set (falls back to the cannon's own location if it is in the target world, otherwise the target world's spawn)

After creation, the plugin replies with the absolute config file path so you can edit displayName, customModel, requiredPermission, the search radii, and the launch tuning manually.

FreeMinecraftModels Integration

When a cannon resolves to a valid FreeMinecraftModels model -- either via 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 to 2.0 blocks above the cannon (vs 1.2 with no model) so it does not clip the model
• idle orbit-particle animation is suppressed while a model is active
• during a launch, the cannon plays its fire animation (if one exists) at the start of the searching phase; the player is hidden with Invisibility during the searching phase so the animation reads cleanly

If FreeMinecraftModels is enabled or disabled while the server is running, the cannon model cache is invalidated and the visuals refresh on the next tick.

Idle Particle Fallback

When no model is active, the cannon renders a pair of orbiting DUST_COLOR_TRANSITION + FIREWORK particles around the cannon center. The colors shift based on the cannon's effective state:

State	Primary	Accent
Ready	orange (255, 179, 71)	pale gold (255, 241, 168)
Searching (charging / maintaining)	warm orange (255, 140, 66)	gold (255, 209, 102)
Exhausted	red (255, 107, 107)	warm orange (255, 159, 104)

Idle particles are only rendered when a player is within 36 blocks of the cannon, enableParticles is true, and no custom model is active.

Floating Status Label

Every cannon spawns a billboarded TextDisplay above its base, showing the display name and the current status (Ready, Charging, Maintaining, Exhausted, or Disabled). The label is non-persistent (it never saves to chunk data) and is recreated automatically on chunk reload. It sits 1.2 blocks above the cannon, or 2.0 blocks when a FreeMinecraftModels model is active.

Runtime Validation Behavior

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

• the target world is unloaded
• the search center cannot be resolved (which only happens when the target world is unloaded)
• the random sample lands outside the world border
• the candidate chunk fails to load
• no safe solid non-liquid surface is found
• any block of the 52-block airdrop column above the landing spot is blocked
• the surface or any column block matches the configured unsafe material lists
• a protection integration blocks the landing
• a CannonRTPLocationValidationEvent listener vetoes the candidate

After searchTimeoutAttempts failed searches (default 100), preloading can become Exhausted. Destinations already in the queue remain usable. An activation returns the configured failure message only when the queue is empty; that message summarizes common rejection reasons. Opening a queue slot after a launch resets the timeout counter.

The target terrain must already exist: candidate chunks are loaded without generating new terrain. Generate or explore the configured search area first; a new world's unexplored search radius may otherwise leave the queue empty.

Interaction Guard

CannonRTP prevents a player from triggering a cannon while they are already in an active launch sequence. That trigger remains latched until the launch is over and the player has actually left the cannon's trigger radius, so recovery back to the cannon seat cannot immediately start another launch. After a launch is accepted, a manager-wide per-player cooldown also blocks every cannon for runtime.launchCooldownSeconds (default 30 seconds). The cooldown survives disconnects while the server keeps running, uses a monotonic clock, and is cleared by /wc reload or plugin shutdown. Entering a cannon early sends the configurable launchCooldown message; set the config value to 0 to disable this gate.