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)
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, 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	Con qué frecuencia se renderizan las partículas inactivas del cañón (mínimo 5)
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.

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; de lo contrario el cañón aparece como Invalid.
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	dorado
Searching (charging / maintaining)	naranja cálido	dorado
Exhausted	rojo	rojo cálido
Invalid configuration	rojo profundo	rojo

Las partículas en reposo solo se renderizan cuando un jugador está a menos de 36 bloques del cañón.

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, Disabled o Invalid). La etiqueta no es persistente (nunca se guarda en datos de chunk) y se recrea automáticamente al recargarse el chunk.

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 es válido
• 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
• el espacio de pies o cabeza está bloqueado
• los bloques del terreno o del cuerpo coinciden con las listas configuradas de materiales inseguros
• una integración de protección bloquea el aterrizaje
• un listener de CannonRTPLocationValidationEvent veta al candidato

Si un cañón consume todos sus searchTimeoutAttempts (por defecto 100) sin completar su reserva, se vuelve Exhausted y empieza a devolver el mensaje de fallo configurado en lugar de lanzar jugadores. El mensaje de fallo incluye un resumen de las razones de rechazo más comunes. El cañón reinicia su contador de tiempo agotado cada vez que se libera un espacio en la cola (p. ej. después de un lanzamiento).

Protección de Interacción

CannonRTP evita que un jugador active un cañón mientras ya está en una secuencia de lanzamiento activa. Una vez que el lanzamiento actual finaliza (aterrizaje o desconexión), el jugador puede usar un cañón de nuevo. No hay un temporizador de cooldown adicional.