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)
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, 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	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, the orbit-particle fallback is used.
runtime.spigotResourceId	""	Spigot resource id used by the version checker. Leave blank to disable.

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, otherwise the cannon shows as Invalid.
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	gold
Searching (charging / maintaining)	warm orange	gold
Exhausted	red	warm red
Invalid configuration	deep red	red

Idle particles are only rendered when a player is within 36 blocks of the cannon.

Floating Status Label

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

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
• the candidate chunk fails to load
• no safe solid non-liquid 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
• a CannonRTPLocationValidationEvent listener vetoes the candidate

If a cannon burns through searchTimeoutAttempts (default 100) without filling its reserve, 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 resets its timeout counter whenever a queue slot opens up (e.g. after a launch).

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.