Configuración de CannonRTP

CannonRTP divide su configuración global entre varios archivos en plugins/CannonRTP/, más un archivo de configuración por cañón en plugins/CannonRTP/cannons/.

Estructura de Archivos

Archivo	Propósito
plugins/CannonRTP/config.yml	Indicadores de ejecución de nivel superior (estado de configuración inicial, idioma, intervalo de partículas, prioridad de modelos de cañón, id de recurso de Spigot, interruptor de actualización automática de Nightbreak)
plugins/CannonRTP/landing.yml	Ajuste de la búsqueda de aterrizaje (tamaño de cola, intentos de tiempo agotado, duración de caída lenta, listas de materiales inseguros, comportamiento fail-open)
plugins/CannonRTP/sounds.yml	Sonidos reproducidos durante la secuencia de lanzamiento
plugins/CannonRTP/messages.yml	Todos los mensajes dirigidos a jugadores, prefijos y conjuntos de títulos
plugins/CannonRTP/protection.yml	Interruptores de integración de protección por plugin
plugins/CannonRTP/cannons/<id>.yml	Un archivo por cañón (cada uno puede gestionar varias colocaciones)
plugins/CannonRTP/cannons_disabled/	Carpeta de retención para configuraciones de cañón que vienen con paquetes de contenido pero están actualmente desactivadas. El menú de /wc setup mueve archivos entre cannons/ y cannons_disabled/ cuando activas o desactivas un paquete de contenido.
plugins/CannonRTP/content_packages/<package>.yml	Metadatos generados para cada paquete de contenido de Nightbreak (versión, enlace de descarga, prefijos usados para encontrar sus archivos). Normalmente no se edita a mano.

El plugin incluye tres configuraciones de cañón de ejemplo de fábrica:

• example_cannonrtp.yml -- plantilla de referencia vacía (nombre de visualización Example World Cannon), desactivada por defecto. Úsala como referencia YAML al escribir archivos de cañón a mano.
• cannonrtp_free_cannon.yml -- activada, sin colocaciones, apunta al modelo FMM gratuito cannonrtp.
• cannonrtp_premium_cannon.yml -- activada, sin colocaciones, apunta al modelo FMM premium cannonrtp_premium.

Ninguna de ellas tiene cannonLocations completado por defecto, por lo que nada aparece en el mundo hasta que un administrador ejecute /wc create o /wc place.

config.yml

Clave	Predeterminado	Comportamiento
setupDone	false	Indica si la configuración inicial estilo Nightbreak se ha completado
language	english	Archivo de traducción a cargar. La versión 1 incluye solo inglés; la clave existe para futuros paquetes de traducción
runtime.particleIntervalTicks	15	Intervalo exacto entre renderizados de partículas de cañón en reposo, en ticks del servidor (mínimo 1; usa 1 para renderizar en cada tick)
runtime.launchCooldownSeconds	30	Segundos que un jugador debe esperar entre lanzamientos de cañón aceptados (mínimo 0; usa 0 para desactivarlo). Los CannonRTPLaunchEvent cancelados no inician el cooldown.
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Lista de prioridad de nombres de modelos de FreeMinecraftModels, revisados de arriba a abajo. El primer modelo encontrado en el servidor se usa para cualquier cañón que no establezca su propio customModel. Si no se encuentra ninguno, se usa el fallback de partículas en órbita.
runtime.spigotResourceId	""	Id de recurso de Spigot usado por el verificador de versiones. Déjalo vacío para desactivarlo.
nightbreak.autoDownloadPluginUpdates	false	Añadido por la librería integrada MagmaCore. Cuando es true, CannonRTP descarga automáticamente los archivos de actualización de plugin y de contenido disponibles al iniciar (se aplican tras el siguiente reinicio del servidor). Las descargas automáticas de plugin requieren un token de cuenta de Nightbreak válido y una membresía de supporter activa. Déjalo en false para usar en su lugar el botón de actualización dentro del juego.

landing.yml

Clave	Predeterminado	Comportamiento
preloadedLocationsPerCannon	10	Número total de destinos seguros que el plugin intenta mantener en cola por cañón (mínimo 1)
chargedLocationsPerCannon	1	Cuántas ubicaciones debe tener un cañón antes de que su etiqueta de estado cambie a Ready (mínimo 1, limitado a preloadedLocationsPerCannon). Los cañones lanzarán jugadores en cuanto la cola tenga al menos una ubicación -- este umbral solo afecta la etiqueta visual.
searchTimeoutAttempts	100	Cuántos intentos de búsqueda fallidos antes de marcar un cañón como Exhausted (mínimo 10). Los intentos de búsqueda están globalmente limitados a uno por tick (20 por segundo), repartidos equitativamente entre todos los cañones activos.
slowFallingSeconds	60	Duración máxima de Caída Lenta después del airdrop (mínimo 1). El efecto se elimina anticipadamente cuando el jugador aterriza.
failOpenOnProtectionErrors	false	Si una API de plugin de protección falla, bloquear el aterrizaje por defecto. Establece true para permitir que los aterrizajes continúen cuando un plugin de protección no se puede consultar de forma segura.
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Materiales que descalifican una superficie de aterrizaje
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Materiales que descalifican el espacio de pies o cabeza de un aterrizaje

Los materiales son nombres del enum Material de Bukkit. Las entradas inválidas se registran como advertencias y se omiten.

sounds.yml

Clave	Predeterminado	Comportamiento
levitationStart.sound	BLOCK_BEACON_ACTIVATE	Sonido reproducido cuando comienza la fase de búsqueda
levitationStart.volume	1.0
levitationStart.pitch	1.15
blastOff.sound	ENTITY_GENERIC_EXPLODE	Sonido reproducido al inicio de la fase de disparo
blastOff.volume	1.0
blastOff.pitch	0.9

Los valores de sonido pueden ser nombres del enum Sound de Bukkit (p. ej. BLOCK_BEACON_ACTIVATE) o claves con espacio de nombres (p. ej. minecraft:block.beacon.activate). Los nombres de sonido inválidos se registran como advertencias y el sonido se omite silenciosamente en ese paso.

messages.yml

Todos los mensajes admiten gradientes MagmaCore, etiquetas MiniMessage y códigos de color heredados &. El marcador $prefix se reemplaza con el prefijo configurado.

Para ver la lista completa de claves de mensaje, marcadores y los conjuntos de títulos usados por la secuencia de lanzamiento, consulta la página Mensajes y Títulos.

Campos de Configuración por Cañón

Cada archivo de cañón (plugins/CannonRTP/cannons/<id>.yml) almacena estos campos:

Campo	Predeterminado	Notas
isEnabled	true (para cañones recién creados)	Los cañones desactivados no se activan y se muestran como Disabled
displayName	CannonRTP (o el nombre proporcionado al crear)	Usado en mensajes, salida de estado y la etiqueta flotante
cannonLocations	lista vacía	Lista de cadenas serializadas world,x,y,z,pitch,yaw. Una configuración de cañón puede generar muchas colocaciones en el mundo. Gestionado por /wc create, /wc place, /wc remove.
targetWorld	mundo actual al momento de creación	Se admite el objetivo en otro mundo -- establécelo para hacer aterrizar jugadores en un mundo distinto al del cañón. Debe estar cargado en tiempo de ejecución; mientras no lo esté, el cañón deja de precargar y el detalle de su /wc status muestra Target world <name> is not loaded.
searchCenter	null	Si no se establece, el plugin irradia desde la propia ubicación del cañón (cuando el cañón está en el mundo objetivo) o desde el spawn del mundo objetivo
triggerRadius	1.75	Radio alrededor del cañón usado para detectar jugadores cercanos (mínimo 0.5 bloques)
minSearchRadius	500	Distancia mínima de búsqueda de aterrizaje desde el centro de búsqueda (mínimo 0)
maxSearchRadius	5000	Distancia máxima de búsqueda de aterrizaje (siempre limitada a al menos minSearchRadius + 1)
launchWarmupTicks	42	Duración de la fase Searching en ticks (mínimo 1)
verticalBoostTicks	45	Duración de la fase Firing en ticks (mínimo 0)
verticalBoostVelocity	1.35	Velocidad ascendente aplicada en cada tick de la fase de disparo (mínimo 0)
enableParticles	true	Controla la animación de partículas en órbita en reposo. Solo se renderiza cuando no hay un modelo personalizado activo y un jugador está a menos de 36 bloques.
requiredPermission	""	Barrera de permiso adicional opcional para este cañón específico. Los jugadores con cannonrtp.use pero sin este nodo ven el mensaje de sin permiso configurado.
customModel	""	Nombre de modelo de FreeMinecraftModels opcional para este cañón específico. Si está vacío, el plugin recurre a runtime.cannonModelPriority.

Valores Predeterminados al Crear un Cañón

Cuando ejecutas /wc create <id>:

• el id del cañón se convierte a minúsculas y los caracteres distintos de a-z, 0-9, _, - se reemplazan por _
• displayName toma por defecto CannonRTP salvo que se haya usado /wc create <id> <display_name> (los guiones bajos en <display_name> se convierten en espacios)
• la ubicación actual del jugador se añade a cannonLocations
• targetWorld se establece en el mundo actual del jugador
• searchCenter no se establece (recurre a la propia ubicación del cañón si está en el mundo objetivo; de lo contrario al spawn del mundo objetivo)

Tras la creación, el plugin responde con la ruta absoluta del archivo de configuración para que puedas editar displayName, customModel, requiredPermission, los radios de búsqueda y el ajuste del lanzamiento manualmente.

Integración con FreeMinecraftModels

Cuando un cañón resuelve a un modelo válido de FreeMinecraftModels -- ya sea a través de su propio campo customModel o de la lista global runtime.cannonModelPriority -- y FreeMinecraftModels está instalado:

• se genera una entidad de modelo estática en la ubicación del cañón
• la etiqueta de texto flotante se eleva a 2.0 bloques sobre el cañón (frente a 1.2 sin modelo) para que no se solape con el modelo
• la animación de partículas en órbita en reposo se suprime mientras un modelo está activo
• durante un lanzamiento, el cañón reproduce su animación fire (si existe) al comienzo de la fase de búsqueda; el jugador se oculta con Invisibilidad durante la fase de búsqueda para que la animación se vea limpia

Si FreeMinecraftModels se activa o desactiva mientras el servidor está en funcionamiento, la caché de modelos del cañón se invalida y los visuales se refrescan en el siguiente tick.

Fallback de Partículas en Reposo

Cuando no hay un modelo activo, el cañón renderiza un par de partículas DUST_COLOR_TRANSITION + FIREWORK orbitando alrededor del centro del cañón. Los colores cambian según el estado efectivo del cañón:

Estado	Primario	Acento
Ready	naranja (255, 179, 71)	dorado pálido (255, 241, 168)
Searching (charging / maintaining)	naranja cálido (255, 140, 66)	dorado (255, 209, 102)
Exhausted	rojo (255, 107, 107)	naranja cálido (255, 159, 104)

Las partículas en reposo solo se renderizan cuando un jugador está a menos de 36 bloques del cañón, enableParticles es true y no hay ningún modelo personalizado activo.

Etiqueta Flotante de Estado

Cada cañón genera un TextDisplay tipo billboard sobre su base, mostrando el nombre de visualización y el estado actual (Ready, Charging, Maintaining, Exhausted o Disabled). La etiqueta no es persistente (nunca se guarda en datos de chunk) y se recrea automáticamente al recargarse el chunk. Se sitúa 1.2 bloques sobre el cañón, o 2.0 bloques cuando hay un modelo de FreeMinecraftModels activo.

Comportamiento de Validación en Tiempo de Ejecución

CannonRTP rechaza ubicaciones de aterrizaje candidatas cuando falla cualquiera de estas comprobaciones:

• el mundo objetivo no está cargado
• el centro de búsqueda no se puede resolver (lo que solo ocurre cuando el mundo objetivo no está cargado)
• la muestra aleatoria cae fuera del borde del mundo
• el chunk candidato no se carga
• no se encuentra una superficie sólida segura no líquida
• algún bloque de la columna de airdrop de 52 bloques sobre el punto de aterrizaje está bloqueado
• la superficie o algún bloque de la columna coincide con las listas configuradas de materiales inseguros
• una integración de protección bloquea el aterrizaje
• un listener de CannonRTPLocationValidationEvent veta al candidato

Tras searchTimeoutAttempts búsquedas fallidas (100 por defecto), la precarga puede quedar Exhausted. Los destinos ya en cola siguen disponibles. El mensaje de error solo aparece al activar con la cola vacía e incluye los motivos de rechazo más frecuentes. Un hueco liberado tras un lanzamiento reinicia el contador.

Genera o explora el área de búsqueda configurada del mundo de destino antes de usar el cañón. CannonRTP carga chunks existentes sin generar terreno; un radio sin explorar puede quedarse sin destinos.

Protección de Interacción

CannonRTP impide que un jugador active un cañón mientras ya está en una secuencia de lanzamiento activa. Ese activador permanece enganchado hasta que el lanzamiento termina y el jugador ha salido realmente del radio de activación del cañón, de modo que la recuperación de vuelta al asiento del cañón no puede iniciar otro lanzamiento de inmediato. Tras aceptarse un lanzamiento, un cooldown por jugador a nivel de gestor también bloquea todos los cañones durante runtime.launchCooldownSeconds (por defecto 30 segundos). El cooldown sobrevive a las desconexiones mientras el servidor siga en marcha, usa un reloj monotónico y se limpia con /wc reload o al apagarse el plugin. Entrar en un cañón antes de tiempo envía el mensaje configurable launchCooldown; establece el valor de configuración en 0 para desactivar esta barrera.