Configuración de CannonRTP

CannonRTP reparte sus ajustes globales entre varios archivos de plugins/CannonRTP/, además de un archivo por cañón en plugins/CannonRTP/cannons/.

Archivos

Archivo	Propósito
plugins/CannonRTP/config.yml	Ajustes generales: estado de configuración inicial, idioma, intervalo de partículas, tiempo de reutilización de lanzamiento, prioridad de modelos, ID de recurso de Spigot y ajustes de actualización de Nightbreak
plugins/CannonRTP/landing.yml	Ajustes de búsqueda de aterrizajes: tamaño de cola, límite de intentos, duración de caída lenta, materiales inseguros y comportamiento ante errores de protección
plugins/CannonRTP/sounds.yml	Sonidos de la secuencia de lanzamiento
plugins/CannonRTP/messages.yml	Mensajes para jugadores, prefijos y conjuntos de títulos
plugins/CannonRTP/protection.yml	Ajustes de cada integración de protección
plugins/CannonRTP/cannons/<id>.yml	Un archivo por cañón; puede controlar varias colocaciones
plugins/CannonRTP/cannons_disabled/	Configuraciones de cañones de paquetes actualmente deshabilitados. /wc setup mueve archivos entre cannons/ y cannons_disabled/ al habilitar o deshabilitar paquetes.
plugins/CannonRTP/content_packages/<package>.yml	Metadatos generados de cada paquete de Nightbreak: versión, enlace de descarga y prefijos para localizar sus archivos. Normalmente no se editan a mano.
plugins/CannonRTP/imports/	Carpeta para importaciones manuales de contenido. Consulta Paquetes de contenido.
plugins/CannonRTP/nightbreak-changelogs.yml	Estado de lectura de la bandeja compartida /wcchangelog. Consulta Notificaciones de notas de versión.

El plugin incluye tres configuraciones de ejemplo:

• example_cannonrtp.yml: plantilla de referencia vacía, con nombre visible Example World Cannon, deshabilitada por defecto. Úsala como referencia YAML para escribir configuraciones manualmente.
• cannonrtp_free_cannon.yml: habilitada, sin colocaciones y con el modelo gratuito de FMM cannonrtp.
• cannonrtp_premium_cannon.yml: habilitada, sin colocaciones y con el modelo prémium de FMM cannonrtp_premium.

Ninguna incluye ubicaciones en cannonLocations por defecto, por lo que no aparece nada hasta que un administrador ejecute /wc create o /wc place. Ninguna define targetWorld, así que cada colocación hace aterrizar a los jugadores en el mundo en el que se encuentra.

CannonRTP vuelve a crear cualquiera de estos tres archivos que falte en cannons/ cada vez que carga las configuraciones de cañones. Si eliminas uno con /wc delete, o se retira al deshabilitar su paquete de contenido, tras la recarga queda una copia predeterminada nueva sin colocaciones.

config.yml

Clave	Predeterminado	Comportamiento
setupDone	false	Registra si se ha completado la configuración inicial de Nightbreak
language	english	Archivo de traducción que se debe cargar. La versión 1 solo incluye inglés; la clave está prevista para futuros paquetes de traducción
runtime.particleIntervalTicks	15	Intervalo exacto, en ticks del servidor, entre las partículas del cañón en reposo. Mínimo 1; usa 1 para mostrarlas cada tick
runtime.launchCooldownSeconds	30	Segundos de espera por jugador entre lanzamientos aceptados. Mínimo 0; 0 lo deshabilita. Cancelar CannonRTPLaunchEvent no inicia la espera.
runtime.cannonModelPriority	[cannonrtp_premium, cannonrtp]	Nombres de modelos de FreeMinecraftModels por prioridad, de arriba abajo. El primero disponible se usa en los cañones sin customModel propio. Si no hay ninguno, se usan partículas orbitales.
runtime.spigotResourceId	""	ID del recurso de Spigot para comprobar versiones. Vacío deshabilita la comprobación.
nightbreak.autoDownloadPluginUpdates	false	Lo añade MagmaCore, incluido en el JAR. Con true, CannonRTP descarga automáticamente unos minutos después del arranque los archivos de actualizaciones disponibles del plugin y del contenido. Las actualizaciones de contenido se usan tras el siguiente reinicio del servidor; una actualización del plugin sigue lo indicado en nightbreak.applyPluginUpdatesWithoutRestart. Las descargas automáticas del plugin requieren un token válido de Nightbreak y una suscripción activa de colaborador. Déjalo en false para usar el botón de actualización del juego.
nightbreak.applyPluginUpdatesWithoutRestart	never	Lo añade MagmaCore, incluido en el JAR. Decide cuándo se aplica una actualización del plugin descargada, recargando CannonRTP desde el nuevo JAR. never espera al siguiente reinicio. when-empty la aplica de inmediato si no hay jugadores conectados; si los hay, lo comprueba cada 30 segundos y la aplica en cuanto el servidor se queda vacío. immediately la aplica en cuanto termina la descarga. Cualquier otro valor cuenta como never. La recarga cancela los lanzamientos activos, como se describe en Protección de la activación. /wc applypluginupdate aplica a mano una actualización descargada, sea cual sea este ajuste.

landing.yml

Clave	Predeterminado	Comportamiento
preloadedLocationsPerCannon	10	Total de destinos seguros que se intenta mantener en cola por cañón; mínimo 1
chargedLocationsPerCannon	1	Número de ubicaciones necesarias para mostrar Listo. Mínimo 1 y máximo preloadedLocationsPerCannon. El cañón puede lanzar en cuanto haya un destino; este umbral solo afecta a la etiqueta visual.
searchTimeoutAttempts	100	Intentos fallidos antes de marcar el cañón como Agotado; mínimo 10. El límite global es un intento por tick, 20 por segundo, repartido de forma equitativa entre los cañones activos.
slowFallingSeconds	60	Duración máxima de Caída lenta tras el teletransporte; mínimo 1. El efecto se elimina antes si el jugador aterriza.
failOpenOnProtectionErrors	false	Por defecto, un error de la API de protección bloquea el aterrizaje. Con true, se permite continuar si no se puede consultar la protección de forma segura. Con false, una integración de protección habilitada que no haya podido cargarse también impide que todos los cañones busquen (consulta Integraciones de protección).
unsafeGroundMaterials	[LAVA, MAGMA_BLOCK, CAMPFIRE, SOUL_CAMPFIRE, CACTUS, POWDER_SNOW]	Materiales que invalidan una superficie de aterrizaje
unsafeBodyMaterials	[LAVA, WATER, FIRE, SOUL_FIRE, SWEET_BERRY_BUSH, POWDER_SNOW, COBWEB]	Materiales prohibidos en toda la columna vertical de aterrizaje y descenso, incluido el espacio de la cabeza al llegar

Los materiales son nombres del enum Material de Bukkit. Las entradas no válidas se omiten con un aviso en el registro.

sounds.yml

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

Los sonidos pueden ser nombres del enum Sound de Bukkit, como BLOCK_BEACON_ACTIVATE, o claves con espacio de nombres, como minecraft:block.beacon.activate. Un nombre de estilo enum se convierte sustituyendo cada guion bajo por un punto, así que un sonido cuya clave contenga un guion bajo, como minecraft:block.note_block.pling, debe escribirse con su clave con espacio de nombres. Los nombres no válidos generan un aviso y se omite el sonido en ese paso. Deja un sonido en blanco para no reproducir nada. Los valores de volumen y tono inferiores a 0 se elevan a 0.

messages.yml

Todos los mensajes admiten degradados de MagmaCore, etiquetas MiniMessage y códigos de color clásicos &. $prefix se sustituye por el prefijo configurado.

Consulta la lista completa de claves, marcadores y conjuntos de títulos de la secuencia en Mensajes y títulos.

Campos de cada cañón

Cada archivo plugins/CannonRTP/cannons/<id>.yml guarda estos campos:

Campo	Predeterminado	Notas
isEnabled	true para cañones nuevos	Los cañones deshabilitados no se activan, no crean etiqueta ni modelo y aparecen como Deshabilitado en /wc list y /wc status
displayName	CannonRTP o el nombre indicado al crear	Se usa en mensajes, información de estado y etiqueta flotante
cannonLocations	Lista vacía	Cadenas serializadas world,x,y,z,yaw,pitch. Una configuración puede crear varias colocaciones. Se gestiona con /wc create, /wc place y /wc remove.
targetWorld	Mundo actual al crear	Permite aterrizar en un mundo distinto al del cañón. Si está vacío o no existe, cada colocación hace aterrizar a los jugadores en su propio mundo. Debe estar cargado; mientras no lo esté, se detiene la precarga y /wc status indica Target world <name> is not loaded..
searchCenter	null	Si no se define, la búsqueda parte de la ubicación del cañón cuando esté en el mundo de destino, o del punto de aparición del mundo de destino en caso contrario. Si se define en una ubicación de otro mundo, se usan sus coordenadas X y Z en el mundo de destino.
triggerRadius	1.75	Radio de detección alrededor del cañón; mínimo 0.5 bloques
minSearchRadius	500	Distancia mínima de búsqueda desde el centro; mínimo 0
maxSearchRadius	5000	Distancia máxima de búsqueda; se ajusta para ser al menos minSearchRadius + 1
launchWarmupTicks	42	Duración en ticks de la fase de búsqueda; mínimo 1
verticalBoostTicks	45	Duración en ticks de la fase de disparo; mínimo 0. Con 0 se omite el impulso ascendente; el sonido de disparo, el estallido y el título del destino se siguen reproduciendo antes del teletransporte.
verticalBoostVelocity	1.35	Velocidad ascendente aplicada cada tick de disparo; mínimo 0
enableParticles	true	Controla las partículas orbitales en reposo. Solo aparecen sin modelo personalizado activo y con un jugador a menos de 36 bloques.
requiredPermission	""	Permiso adicional opcional del cañón. Los jugadores con cannonrtp.use pero sin este nodo reciben el mensaje configurado de falta de permiso.
customModel	""	Nombre opcional de modelo de FreeMinecraftModels para este cañón. Si está vacío o no está disponible, se recurre a runtime.cannonModelPriority.

Valores iniciales al crear cañones

Al ejecutar /wc create <id>:

• El ID se convierte a minúsculas y los caracteres distintos de a-z, 0-9, _ y - se sustituyen por _.
• displayName pasa a CannonRTP, salvo que se use /wc create <id> <display_name>; los guiones bajos del nombre visible se convierten en espacios.
• La ubicación actual del jugador se añade a cannonLocations.
• targetWorld se establece en el mundo actual del jugador.
• No se define searchCenter; se usa la ubicación del cañón si está en el mundo de destino o, en caso contrario, el punto de aparición de ese mundo.

Después, el plugin responde con la ruta absoluta del archivo para que puedas editar manualmente displayName, customModel, requiredPermission, los radios de búsqueda y los ajustes del lanzamiento.

Integración con FreeMinecraftModels

Si FreeMinecraftModels está instalado y se encuentra un modelo válido mediante customModel o runtime.cannonModelPriority:

• Se crea una entidad de modelo estático en la ubicación del cañón.
• La etiqueta flotante sube a 2.0 bloques sobre el cañón, frente a 1.2 sin modelo, para no atravesarlo.
• Se suprimen las partículas orbitales en reposo mientras el modelo esté activo.
• Al comenzar la búsqueda de un lanzamiento, el cañón reproduce su animación fire si existe y se oculta al jugador con Invisibilidad durante esa fase para que la animación se vea correctamente.

Habilitar o deshabilitar FreeMinecraftModels durante la ejecución invalida la caché de modelos de cañones. Las versiones actuales de FMM también avisan al terminar una recarga de contenido, para descartar referencias antiguas y recrear los modelos desde el registro actualizado. CannonRTP también detecta directamente las instancias de modelos eliminadas, incluso con FMM 2.4.0, que es anterior al evento de recarga completada. Mientras FMM esté habilitado, la recreación pendiente se reintenta cada 20 ticks hasta que haya un modelo utilizable.

Partículas alternativas en reposo

Sin un modelo activo, el cañón muestra un par de partículas DUST_COLOR_TRANSITION + FIREWORK orbitando alrededor de su centro. Los colores cambian según el estado efectivo:

Estado	Color principal	Color secundario
Listo	Naranja, 255, 179, 71	Dorado pálido, 255, 241, 168
Buscando: cargando o reponiendo	Naranja cálido, 255, 140, 66	Dorado, 255, 209, 102
Agotado	Rojo, 255, 107, 107	Naranja cálido, 255, 159, 104

Solo se muestran si hay un jugador a menos de 36 bloques, enableParticles es true y no hay un modelo personalizado activo.

Etiqueta flotante de estado

Cada cañón habilitado crea un TextDisplay orientado al observador sobre su base, con el nombre visible y el estado actual: Ready, Charging, Maintaining o Exhausted. Los cañones deshabilitados no crean etiqueta. La etiqueta no es persistente, no se guarda en los datos del chunk y se recrea automáticamente al cargarlo. Se sitúa a 1.2 bloques sobre el cañón, o a 2.0 con un modelo de FreeMinecraftModels activo.

Validación durante la ejecución

CannonRTP rechaza los candidatos de aterrizaje cuando falla alguna de estas comprobaciones:

• El mundo de destino está descargado.
• No se puede resolver el centro de búsqueda, lo que solo ocurre si el mundo de destino está descargado.
• La muestra aleatoria cae fuera del borde del mundo.
• No se puede cargar el chunk candidato.
• No se encuentra una superficie segura, sólida y no líquida.
• Algún bloque de la columna de descenso de 52 bloques está obstruido.
• La superficie o algún bloque de la columna coincide con las listas de materiales inseguros.
• Una integración de protección bloquea el aterrizaje.
• Un listener de CannonRTPLocationValidationEvent rechaza el candidato.

Tras searchTimeoutAttempts búsquedas fallidas, 100 por defecto, la precarga puede quedar Agotada. Los destinos que ya estén en cola siguen siendo utilizables. Al activar el cañón, solo se devuelve el mensaje de fallo si la cola está vacía; el mensaje resume los motivos de rechazo habituales. Liberar un hueco tras un lanzamiento reinicia el contador de intentos.

El terreno de destino debe existir: los chunks candidatos se cargan sin generar terreno nuevo. Genera o explora primero el área de búsqueda; de lo contrario, un radio sin explorar en un mundo nuevo puede dejar la cola vacía.

Protección de la activación

CannonRTP impide activar un cañón durante una secuencia de lanzamiento activa. El bloqueo permanece hasta que termine la secuencia y el jugador haya salido realmente del radio del cañón, evitando que recuperarlo en el asiento provoque otro lanzamiento inmediato. Tras aceptar un lanzamiento, un tiempo de reutilización global por jugador bloquea todos los cañones durante runtime.launchCooldownSeconds, 30 segundos por defecto. Se conserva durante desconexiones mientras el servidor siga en marcha, usa un reloj monotónico y se borra cada vez que CannonRTP reconstruye sus cañones: con /wc reload, con una actualización del plugin sin reinicio, al deshabilitar el plugin o con cualquier comando de edición de cañones (create, place, remove, delete, target, center). Una reconstrucción también cancela los lanzamientos activos, devuelve a esos jugadores al asiento de su cañón y descarta todos los destinos en cola. Entrar antes de tiempo envía el mensaje configurable launchCooldown; usa 0 en la configuración para deshabilitar esta espera.