Documentación · índice

[09] Documentación

BoatRacing.

Documentación completa de BoatRacing 26.3: instalación, equipos, pistas, AutoTrace, checkpoints, carreras, comandos, permisos, configuración, placeholders y API de extensiones.

Última revisión · noviembre 2026 · BoatRacing 26.3

Contenido

Esta guía reproduce la referencia pública del README de BoatRacing y añade las claves reales de config.yml de la versión 26.3. Usa los enlaces para saltar a cada bloque.

Qué es BoatRacing

BoatRacing es un plugin de carreras de botes sobre hielo con estética de F1 para servidores Bukkit, Spigot, Paper, Purpur y Folia. Gestiona equipos, circuitos, checkpoints, paradas en boxes, espectadores, cosméticos y estadísticas con una interfaz vanilla y una API de extensiones.

  • Versión documentada: 26.3. Licencia: MIT. Idiomas: 27 paquetes; inglés y español son oficiales.
  • Pistas con nombre: cada circuito vive en plugins/BoatRacing/tracks/<nombre>.yml y puede sobrescribir vueltas, pits, tiempos, penalizaciones, lobby, recompensas y otros ajustes de racing.*.
  • Creación de pistas: varita de selección, regiones cúbicas, AutoTrace conduciendo una vuelta, puertas orientadas, puertas alternativas, asistente guiado, undo/redo, copiar/pegar y validación.
  • Carreras: checkpoints ordenados, pits opcionales, paradas obligatorias, falsa salida, 5 luces, lobby de inscripción, DNF, recuperación tras caída, práctica con ghosts, replay y espectadores.
  • Progresión: 24 estelas, títulos por victorias, efectos y sonidos de victoria, efectos de checkpoint, densidad de partículas y tienda Vault.
  • Integraciones: PlaceholderAPI, Vault, SimpleScore, TAB, Discord webhooks, bStats y actualizaciones desde Modrinth.
BoatRacing es aditivo: las configuraciones, pistas y mensajes antiguos siguen cargando; las claves nuevas se fusionan sin sobrescribir las que ya hayas cambiado.

Requisitos y compatibilidad

  • Java 17 o superior.
  • Minecraft 1.19 a 26.3 en CraftBukkit, Spigot, Paper, Purpur o Folia.
  • Opcional: PlaceholderAPI para los placeholders %boatracing_*%.
  • Opcional: Vault y un plugin de economía para la tienda de cosméticos y la economía de carrera.
  • Opcional: SimpleScore para ocultar y restaurar el sidebar externo durante las carreras; TAB también es compatible como entorno de scoreboard.
  • No soportado: proxies Velocity/BungeeCord como destino de la lógica de juego, ni híbridos Sponge/Forge como Mohist, Magma o Arclight.

El jar es único para la familia Bukkit y declara folia-supported: true. Usa resolución dinámica de materiales de botes y balsas, así que los tipos nuevos (por ejemplo Poplar en 26.3) funcionan sin cambiar la compilación.

Hay 27 bundles: en y es oficiales; es_419, fr, pt_BR, pt_PT, de, it, pl, tr, ja, ko, sv, zh_TW, zh_CN, ru, uk, id, ar, nl, cs, vi, th, tl, da, no y fi comunitarios. Todos están completos para 26.3. Puedes añadir messages_<idioma>.yml en plugins/BoatRacing/lang/ y seleccionarlo con language.

Instalación

  1. 01

    Descarga el jar

    Usa la versión publicada en Modrinth que coincida con tu servidor. La versión estable documentada aquí es 26.3.

  2. 02

    Colócalo en plugins

    Sube BoatRacing.jar a plugins/. No hace falta una segunda dependencia: el plugin funciona solo.

  3. 03

    Arranca una vez

    El primer inicio genera config.yml, mensajes, datos, la carpeta tracks/ y la base de datos por defecto. Después puedes configurar pistas sin reiniciar.

  4. 04

    Dependencias opcionales

    Instala PlaceholderAPI para placeholders, Vault + economía para la tienda y la economía de carrera, y SimpleScore o TAB si quieres integrar el sidebar.

  5. 05

    Comprueba el comando

    Ejecuta /boatracing o /boatracing version. Si no aparece, revisa que el jar sea Bukkit y que la versión de Java sea 17 o superior.

El almacenamiento por defecto es SQLite (plugins/BoatRacing/boatracing.db). Los drivers JDBC se descargan en el primer uso desde Maven Central, con verificación SHA-256, y se cachean en plugins/BoatRacing/lib/; si no están disponibles, BoatRacing cae a YAML.

Inicio rápido

  1. 01

    Crea o únete a un equipo

    /boatracing teams. Sin equipo no puedes inscribirte en una carrera. Configura tu dorsal y tu bote desde la GUI o con /boatracing teams number y /boatracing teams boat.

  2. 02

    Crea o selecciona una pista

    /boatracing admin tracks o /boatracing setup select <pista>. Todo se guarda en plugins/BoatRacing/tracks/<pista>.yml.

  3. 03

    Configura la pista

    La vía recomendada es /boatracing setup wizard. Para ajustes rápidos usa la varita, los tintes de puertas y AutoTrace.

  4. 04

    Abre la inscripción

    /boatracing race open <pista>. Los jugadores entran con /boatracing race join <pista>.

  5. 05

    Inicia la carrera

    /boatracing race start <pista> o /boatracing race force <pista>. También puede auto-iniciarse al terminar el tiempo de inscripción.

  6. 06

    Cosméticos y estadísticas

    /boatracing cosmetics, /boatracing cosmetics density normal y /boatracing stats [jugador].

  7. 07

    Si algo falla

    /boatracing debug imprime un informe seguro y el enlace fijo a GitHub Issues. Adjunta también logs/latest.log.

Equipos y perfil

/boatracing teams abre una GUI para ver equipos, abrir un equipo, unirse o salir, gestionar tu dorsal y tu bote y, si la configuración lo permite, renombrar, cambiar el color o disolver el equipo. El perfil de equipo muestra el título y la estela del jugador y abre el menú de cosméticos.

  • Tamaño máximo: max-members-per-team, por defecto 2.
  • Líder: los placeholders de líder resuelven siempre al líder guardado actual. Si el líder sale, la jefatura pasa al siguiente miembro guardado.
  • Último miembro: al salir el último miembro, el equipo se elimina; la GUI y el comando piden confirmación.
  • Permisos de jugador: player-actions.allow-team-create, allow-team-rename, allow-team-color, allow-team-disband, allow-set-boat y allow-set-number; los valores por defecto permiten crear equipo, cambiar bote y dorsal.
  • Administración: los administradores pueden crear, borrar, renombrar, recolorear, añadir y quitar miembros sin depender de esos ajustes.
ComandoUso
/boatracing teamsAbre la GUI para crear, buscar, entrar o gestionar tu equipo.
/boatracing teams create <nombre>Crea un equipo; el jugador debe estar sin equipo.
/boatracing teams rename <nuevo nombre>Renombra el equipo si la configuración lo permite.
/boatracing teams color <DyeColor>Cambia el color del equipo si está permitido.
/boatracing teams join <team>Entra en un equipo con hueco libre.
/boatracing teams leaveSale del equipo; si eres el último miembro pide confirmación.
/boatracing teams boat <tipo>Elige bote, bote con cofre o balsa.
/boatracing teams number <1-99>Asigna tu dorsal de carrera.
/boatracing teams confirmConfirma una acción pendiente, como disolver al salir el último miembro.
/boatracing teams cancelCancela la confirmación pendiente.

Comandos

El comando raíz es /boatracing; en la tabla aparece como /boatracing para que se vea el contexto completo. Los subcomandos de pista aceptan nombres con espacios cuando el nombre se pasa entre comillas (por ejemplo, setpit "Toast Peace").

Comandos raíz

ComandoUso
/boatracing teamsAbre la GUI de equipos del jugador.
/boatracing race helpMuestra la ayuda y los subcomandos de carrera.
/boatracing stats [jugador]Abre la GUI de estadísticas; en consola devuelve el informe de texto.
/boatracing setup helpLista todos los comandos de configuración de pistas.
/boatracing adminAbre el panel de administración.
/boatracing cosmeticsAbre el menú de cosméticos.
/boatracing cosmetics density <low|normal|high>Cambia la densidad de partículas del jugador.
/boatracing cosmetics unlock|revoke|unlocks ...Gestión de desbloqueos para administradores.
/boatracing extensions [reload]Lista o recarga las extensiones gestionadas por BoatRacing.
/boatracing reloadRecarga configuración, mensajes y datos.
/boatracing versionMuestra versión y estado de actualización.
/boatracing debugInforme de diagnóstico solo para administradores.

Comandos de carrera

ComandoUso
/boatracing race helpMuestra la ayuda de carrera.
/boatracing race open <track> [party|normal]Abre la inscripción; el modo party solo existe si el addon está instalado.
/boatracing race join <track>Entra en la inscripción de esa pista.
/boatracing race leave <track>Sale de la inscripción.
/boatracing race backVuelve a la ubicación guardada antes del lobby.
/boatracing race start <track>Inicia la carrera con los jugadores inscritos.
/boatracing race force <track>Fuerza el inicio con los inscritos.
/boatracing race restart [pista]Detiene, reabre, reinscribe y fuerza el inicio; detecta la pista si se omite.
/boatracing race practice <track>Inicia una práctica individual en una pista lista.
/boatracing race practice leave <track>Sale de una sesión de práctica.
/boatracing race forfeitAbandona la carrera activa y aparece como DNF.
/boatracing race stop <track>Cancela la inscripción o la carrera de esa pista.
/boatracing race status <track>Muestra estado, vueltas, modo party y preparación de la pista.
/boatracing race voteopen [all|<pistas>] [segundos]Abre una votación de mapa; sin pistas usa todas.
/boatracing race vote <track>Emite tu voto; sin pista abre la interfaz si hay votación.
/boatracing race voteuiAbre el panel de votación.
/boatracing race votestatusMuestra los votos actuales.
/boatracing race votecloseCierra y resuelve la votación.
/boatracing race spectate [leave|<track>]Entra o sale del modo espectador.
Consola y administradores pueden usar -p:<jugador> para dirigir comandos como /boatracing stats -p:<jugador> a otro jugador. En /boatracing race, los verbos de administración solo se sugieren a quien puede usarlos.

Crear una pista

Hay dos formas de construir una pista y ambas escriben el mismo archivo tracks/<nombre>.yml: el asistente guiado y los comandos manuales. En ambos casos, crea o selecciona primero la pista con /boatracing admin tracks o /boatracing setup select <pista>.

  • Asistente: /boatracing setup wizard. Recorre salidas, meta, luces, pit, checkpoints, paradas, vueltas y tiempo de inscripción con títulos en pantalla y botones [Next] [Skip] [Back].
  • Manual: usa la varita, los tintes de puertas y AutoTrace. Es más rápido cuando ya conoces el trazado o quieres retocar una pista existente.
  • Varita: Blaze Rod llamada BoatRacing Selection Tool; clic izquierdo marca la esquina A y clic derecho la B.
  • Requisito de pista lista: al menos 1 slot de salida y una meta. El pit y los checkpoints son opcionales; las luces son opcionales, pero si se usan deben ser exactamente 5.
  • Luces con varita: Shift + clic izquierdo añade la lámpara de redstone que estás mirando y Shift + clic derecho la quita; el orden es de izquierda a derecha.
  • Pistas con nombre: puedes tener varias sesiones de carrera independientes en pistas distintas.
La meta es una región; los checkpoints son líneas que se cruzan, no zonas donde haya que quedarse. El pit sí es un área real y cuenta entradas/salidas.

Comandos de setup

Todos requieren boatracing.setup salvo que se indique otra cosa. Los cambios de vueltas, paradas, tiempo de inscripción y cosméticos se aplican a la pista activa al instante; no hace falta reiniciar ni recargar.

ComandoQué hace
/boatracing setup helpLista los comandos de configuración.
/boatracing setup select <track>Selecciona la pista activa para configurar.
/boatracing setup wizardInicia el asistente guiado; acepta next, skip, back, status, finish y cancel.
/boatracing setup wandEntrega la varita de selección (Blaze Rod).
/boatracing setup gates [off]Entrega o retira los tintes de checkpoints/meta.
/boatracing setup addstartAñade tu posición actual como slot de salida; se pueden añadir varios.
/boatracing setup clearstartsElimina todos los slots de salida.
/boatracing setup removestart <slot>Elimina un slot concreto (empieza en 1).
/boatracing setup setfinishGuarda la selección como región de meta.
/boatracing setup clearfinishElimina la meta.
/boatracing setup setpit [equipo]Guarda el pit por defecto o uno específico de equipo.
/boatracing setup clearpitElimina el pit por defecto.
/boatracing setup addcheckpointAñade un checkpoint en orden desde la selección.
/boatracing setup clearcheckpointsElimina todos los checkpoints.
/boatracing setup addalt <#>Añade una puerta alternativa a un checkpoint; cruzarla también cuenta.
/boatracing setup clearalt <#>Elimina las puertas alternativas de un checkpoint.
/boatracing setup addlightAñade la lámpara de redstone que estás mirando como luz de salida; máximo 5.
/boatracing setup removelight <índice>Elimina una luz concreta (empieza en 1).
/boatracing setup clearlightsElimina todas las luces de salida.
/boatracing setup setlaps <n>Guarda y aplica las vueltas al instante.
/boatracing setup setpitstops <n>Guarda y aplica las paradas obligatorias; 0 las desactiva.
/boatracing setup setregtime <segundos>Guarda el tiempo de inscripción de la pista.
/boatracing setup setcosmetics <true|false>Activa o desactiva cosméticos en la pista activa.
/boatracing setup setlobbyGuarda tu posición como lobby de inscripción y lo activa.
/boatracing setup clearlobbyDesactiva el lobby de la pista.
/boatracing setup setpos <player> <slot|auto>Ata un jugador a una salida o quita el atajo con auto.
/boatracing setup clearpos <player>Elimina el slot personalizado de un jugador.
/boatracing setup showResumen de salidas, luces, meta, pits, checkpoints y overrides.
/boatracing setup selinfoMuestra información de depuración de la selección.
/boatracing setup undoDeshace el último cambio de checkpoints o meta.
/boatracing setup redoRehace el último cambio deshecho.
/boatracing setup copyCopia los checkpoints actuales al portapapeles de setup.
/boatracing setup paste [dx dy dz]Pega los checkpoints copiados con un desplazamiento opcional.
/boatracing setup validateInforma de elementos que faltan o no son válidos.
setup show también imprime los overrides activos de la pista. setup validate es la forma rápida de detectar salidas, meta o luces que falten antes de abrir una carrera.

AutoTrace

AutoTrace graba una vuelta conducida y genera puertas de checkpoint orientadas a lo largo del recorrido. No crea salidas, luces ni meta: solo los checkpoints.

  1. 01

    Empieza a grabar

    Sube a un bote y ejecuta /boatracing setup autotrace start. Recibes un título AUTOTRACE, coordenadas, marcador de inicio, barra de acción y botones clicables.

  2. 02

    Conduce una vuelta limpia

    No coloques checkpoints a mano: se generan desde tu línea. La grabación se detiene al acercarte al inicio (auto-close-distance) o con [Stop]; si llevas el tinte amarillo, colocar la meta también la detiene y genera las puertas.

  3. 03

    Revisa y edita

    /boatracing setup autotrace preview activa la previsualización. Con la varita, clic izquierdo selecciona una puerta y clic derecho la deselecciona; usa resize selected o delete selected para editarlas en lote.

  4. 04

    Guarda o descarta

    accept guarda y sustituye la lista actual de checkpoints; cancel no toca la pista. Añade puertas manuales después de accept si quieres mezclarlas.

SubcomandoQué hace
/boatracing setup autotrace startEmpieza a grabar una vuelta y genera puertas al terminar.
/boatracing setup autotrace stopDetiene la grabación y genera las puertas desde el recorrido.
/boatracing setup autotrace previewActiva o desactiva la previsualización de partículas.
/boatracing setup autotrace acceptGuarda las puertas generadas y sustituye los checkpoints actuales.
/boatracing setup autotrace cancelDescarta la sesión de AutoTrace.
/boatracing setup autotrace statusMuestra muestras, puertas, longitud y estado de previsualización.
/boatracing setup autotrace delete <índice>Elimina una puerta generada (empieza en 1).
/boatracing setup autotrace resize <índice> <ancho> <alto>Redimensiona una puerta generada.
/boatracing setup autotrace resize selected <ancho> <alto>Redimensiona todas las puertas seleccionadas con la varita.
/boatracing setup autotrace delete selectedElimina todas las puertas seleccionadas con la varita.
/boatracing setup autotrace helpMuestra la guía de seis pasos con botones.

Ajustes en setup.auto-trace.*: enabled, sample-ticks, min-distance, max-samples, simplify-epsilon, spacing, half-width, half-height, auto-close-distance, auto-close-min-length, recenter-ice, start-marker, actionbar, reminder-seconds, preview, preview-period-ticks, preview-particle, preview-view-distance, wand-select, wand-select-radius y selection-particle.

Más puertas generadas significan una ruta más estricta. simplify-epsilon alto y spacing grande reducen el número de puertas; half-width y half-height controlan el tamaño de cada puerta.

Puertas manuales

/boatracing setup gates entrega dos herramientas. El tinte azul coloca un checkpoint orientado hacia donde miras con clic derecho; agachado + clic derecho elimina el último checkpoint. El tinte amarillo coloca la meta; agachado + clic derecho la borra. /boatracing setup gates off retira las herramientas.

  • Mientras sostienes una herramienta, los checkpoints se dibujan con partículas azules y la meta con otro efecto; ambos se configuran en setup.gates.*.
  • La meta usa el mismo ancho y alto que las puertas de checkpoint; solo cambia su profundidad (finish-half-depth).
  • Si colocas la meta amarilla durante una grabación de AutoTrace, la grabación se detiene y se generan las puertas desde el recorrido.
  • Colores y partículas: checkpoint-particle, finish-particle, checkpoint-color y finish-color; la previsualización usa preview, preview-period-ticks y view-distance.

Checkpoints y regiones

Los checkpoints se guardan en orden dentro de tracks/<pista>.yml. Los antiguos son regiones alineadas a los ejes y no necesitan type; los nuevos pueden ser puertas orientadas con type: plane. Una misma lista puede mezclar ambos formatos.

checkpoints:
  - world: world
    minX: 130.0
    minY: 62.0
    minZ: 310.0
    maxX: 138.0
    maxY: 72.0
    maxZ: 312.0

  - type: plane
    world: world
    center: 134.500,64.000,311.000
    normal: 0.000,0.000,-1.000
    right: 1.000,0.000,0.000
    up: 0.000,1.000,0.000
    halfWidth: 4.5
    halfHeight: 3.0
    alternates:
      - world: world
        minX: 120.0
        minY: 62.0
        minZ: 300.0
        maxX: 124.0
        maxY: 72.0
        maxZ: 302.0
  • center, normal, right y up aceptan x,y,z, una lista YAML o el formato de vector de Bukkit.
  • Los archivos sin type se cargan como región AABB y solo se reescriben al editar la pista.
  • alternates puede mezclar puertas AABB y orientadas; cruzando cualquiera de ellas se avanza el checkpoint.
  • Detección: cada movimiento se comprueba como segmento contra el plano dentro del rectángulo. Solo se prueba el siguiente checkpoint en orden, así que tocar una puerta posterior no hace nada.
  • Saltarse checkpoints: si llegas a la meta sin todos, la vuelta se rechaza con un mensaje que indica cuántos faltan. No hay teleport, penalización ni descalificación por salir de la ruta.
  • Meta: es una región; completar la vuelta requiere todos los checkpoints y las paradas obligatorias si están configuradas.
  • Pit: es la única área real. Entrar o salir cuenta paradas, puede aplicar penalización y las paradas obligatorias pueden bloquear la meta.
  • Dirección: hoy no se comprueba; cruzar una puerta hacia atrás también cuenta. El orden es lo que evita atajos.
  • Rendimiento: solo se comprueba al cambiar de bloque, solo a participantes de una carrera activa, solo el siguiente checkpoint y con una caja amplia que evita cálculos lejos de la pista. La detección usa intersección rayo-AABB para no saltarse puertas a alta velocidad.
Las puertas no tienen colisión: puedes conducir por cualquier sitio. Las partículas solo dibujan el contorno y sirven para orientarte.

Asistente guiado

/boatracing setup wizard es la vía guiada para construir una pista. Es un flujo por chat con botones clicables, títulos en pantalla, auto-avance cuando el paso es válido y opción de saltar los pasos opcionales.

  • Pasos: Starts, Finish, Start lights, Pit area, Checkpoints, Mandatory pit stops, Laps y Registration time.
  • Starts: permite añadir salidas y gestionar slots personalizados con botones para setpos/clearpos.
  • Finish y checkpoints: siguen usando la varita de selección; los checkpoints también ofrecen AutoTrace.
  • Pit: distingue pit por defecto y pits por equipo; el segundo es opcional.
  • Navegación: next, skip, back, status, finish y cancel existen, pero no se muestran en tab-completion para no ensuciar la entrada.
  • Al terminar: la pista conserva todo lo guardado en su YAML y puedes seguir editando con comandos manuales o tintes.

Carreras, votos y práctica

El ciclo normal es: equipo → inscripción → salida → 5 luces → checkpoints → pits → meta → resultados. Los jugadores deben pertenecer a un equipo antes de entrar en una inscripción.

  • Sesiones paralelas: varias pistas pueden tener inscripción o carrera a la vez. Un jugador solo puede estar en una sesión a la vez.
  • Bloqueo por pista: una carrera y una práctica no pueden coexistir en la misma pista, tampoco durante la cuenta atrás; otras pistas siguen libres.
  • Inscripción: open <pista> carga los ajustes actuales de la pista, incluyendo overrides racing.*. join exige equipo; leave sale de la inscripción.
  • Mínimo de jugadores: racing.min-players-to-start (por defecto 1), configurable por pista. Se aplica a start, force, inicio desde GUI y auto-inicio por tiempo; la práctica lo ignora.
  • Grid: primero los slots personalizados, después los mejores tiempos registrados en esa pista y al final quienes no tienen tiempo.
  • Botes: se usa el bote, bote con cofre o balsa elegido por cada jugador; los materiales se resuelven de forma compatible entre versiones.
  • Cuenta atrás: 5 lámparas de redstone. Moverse hacia delante antes de apagarse aplica la penalización de falsa salida.
  • Sin desmontar: no se puede salir manualmente del bote/raft durante la cuenta atrás ni mientras la carrera está activa.
  • Checkpoints: si existen, la vuelta solo cuenta al cruzar todos en orden.
  • Pits: entrar puede aplicar penalización; salir cuenta para las paradas obligatorias.
  • Resultados: los resultados se ordenan por tiempo transcurrido más penalizaciones; el ganador actualiza estadísticas de jugador y equipo. El podio usa medallas de oro, plata y bronce y colores por posición.
  • DNF: forfeit abandona la carrera sin pararla para los demás y aparece como DNF al final; no recibe recompensas ni victorias. Una desconexión también puede registrarse como DNF.
  • Recuperación: si el servidor cae o se reinicia a mitad de carrera, BoatRacing guarda la ubicación previa de los participantes para devolverlos al arrancar.

Votaciones de mapa. voteopen [all|<pistas>] [segundos] abre una votación; sin lista usa todas las pistas guardadas. El anuncio incluye un botón para /boatracing race voteui y la instrucción escrita /{label} race vote <pista> para clientes sin clic. Al cerrar, se intenta abrir automáticamente la inscripción de la pista ganadora; si no se puede, el aviso de siguiente paso va solo a quienes gestionan la votación y a la consola.

Práctica. /boatracing race practice <pista> inicia una sesión individual en una pista lista, sin mínimo de jugadores. Los mensajes de cuenta atrás, vuelta y resultado son privados; el sidebar muestra PRACTICE/PRÁCTICA. El ghost del mejor run se captura y se reproduce sin colisión, oculto para los demás y con interpolación suave. practice leave <pista> sale, y desconectar/expulsar también cierra la sesión.

Lobby y regreso. Con racing.lobby.enabled: true, los jugadores van al lobby al inscribirse. return-on-leave los devuelve al salir o cancelar. Tras terminar, cancelar o acabar una práctica, vuelven al lobby y reciben el aviso clicable de /boatracing race back; la ubicación previa se guarda en memoria 180 segundos por defecto. Con racing.lobby.return-after-end: true vuelven directamente a la ubicación previa, sin ventana de back, incluso si el lobby está desactivado.

Espectadores. /boatracing race spectate [pista] permite ver una carrera; spectate leave sale. El modo y la ubicación anteriores se restauran al salir; las tareas de seguimiento se cancelan al salir, desconectar o ser expulsado. racing.spectate-on-finish.mode puede ser off, free o follow; follow usa follow-interval-ticks.

Reinicio. /boatracing race restart [pista] detiene, reabre, reinscribe y fuerza el inicio; si se omite la pista, la detecta. Carreras gestionadas por jugadores: con player-actions.allow-player-race-start: true o el override racing.allow-player-start de la pista, los no administradores pueden abrir, iniciar, forzar y parar.

El ganador se guarda como ghost de la pista si replay.capture-race está activo. Los participantes reciben un aviso de que el ghost de carrera se ha guardado.

Cosméticos y estadísticas

/boatracing cosmetics abre el menú con pestañas de estelas, títulos, efectos de victoria, sonidos de victoria y efectos de checkpoint, más ajustes. El icono de cada pestaña refleja la selección actual. El perfil de equipo muestra título y estela y abre este menú.

  • 24 estelas: smoke, flame, soul, cloud, spark, heart, happy, witch, end_rod, totem, drip, enchant, bubble, snow, lava, note, portal, enchanted, damage, spore, sculk, cherry, drip_lava e ink.
  • Títulos: rookie (0), pro (5), elite (25) y legend (100) por defecto; se pueden comprar o desbloquear con permiso. Sin selección se usa el más alto desbloqueado.
  • Efectos de victoria: default, none, gold, silver, bronze, rainbow, heart, soul y party.
  • Sonidos de victoria: default, none, level_up, chime, bell, pling, firework, dragon, thunder, wither, totem, beacon, portal, anvil y victory.
  • Efectos de checkpoint: none, spark, flame, heart, happy, soul, enchant, note, portal, totem, sculk y cherry.
  • Densidad: low, normal o high; por defecto 1/2/4 partículas por muestra. Se aplica a estelas, checkpoints y fuegos de victoria.
  • Tienda: con Vault, los objetos bloqueados muestran precio y botón [Buy] si cosmetics.shop.enabled está activo. gated-by-default exige permiso, compra o precio 0; default-price: -1 significa solo permisos.
  • Alcance: cosmetics.enabled es el interruptor global; racing.cosmetics-enabled: false o /boatracing setup setcosmetics false desactiva estelas, efectos y sonidos en esa pista.
  • Compatibilidad: los nombres de partículas y sonidos se resuelven con alias; las partículas inexistentes se ocultan (hide) o usan fallback (fallback).
/boatracing cosmetics
/boatracing cosmetics density normal
/boatracing cosmetics unlock <jugador> <trail|title|effect|sound|checkpoint> <id> [30m|12h|7d]
/boatracing cosmetics unlock <jugador> <categoría> * [duración]
/boatracing cosmetics unlock <jugador> all [duración]
/boatracing cosmetics revoke <jugador> <categoría> <id|*>
/boatracing cosmetics revoke <jugador> all
/boatracing cosmetics unlocks <jugador>
/boatracing stats [jugador]

Los permisos individuales son boatracing.cosmetics.trail.<id>, .title.<id>, .effect.<id>, .sound.<id> y .checkpoint.<id>; boatracing.cosmetics.unlock.all no lo concede boatracing.*, solo boatracing.admin. Las preferencias se guardan en player-prefs.yml y las compras/desbloqueos en cosmetic-unlocks.yml (o como documentos del backend).

Estadísticas. /boatracing stats abre la GUI con resumen competitivo y página de práctica paginada; /boatracing stats <jugador> requiere boatracing.stats.others. Incluye equipo, dorsal, bote, título, estela, efecto, victorias, posiciones, mejor carrera, mejor vuelta y práctica por pista. En consola se mantiene el informe de texto.

Economía, recompensas e integraciones

La economía de carrera es opcional y necesita Vault con un proveedor de economía. Se configura en race.economy.*: enabled, entry-fee, refund-on-cancel y prizes.<posición>.

  • Al iniciar, se cobra la entrada a cada participante; quien no puede pagar es devuelto y no participa.
  • Las posiciones que terminan cobran el premio configurado una vez. La práctica nunca cobra ni paga.
  • /boatracing race stop sin resultados reembolsa la entrada si refund-on-cancel: true.
  • Recompensas: racing.rewards.enabled; cada posición acepta commands, messages y broadcast. Placeholders: {player}, {position}, {time}, {track} y {laps}.
  • Compatibilidad: se acepta command singular como legado, pero se recomienda commands en lista. Mantén commands: [] explícito en cada bloque.
  • Por pista: tracks/<pista>.yml puede sobrescribir recompensas y ajustes de carrera.
  • Discord: discord.enabled, webhook-url, username, avatar-url y eventos race-start, race-results y record-broken.
  • Replay: replay.capture-race: true guarda el run del ganador como ghost de la pista, etiquetado como récord de carrera.
  • bStats: activo por defecto; se desactiva con bstats.enabled: false.
  • Actualizaciones: Modrinth, comprobaciones cada 5 minutos, aviso único al detectar versión y recordatorio horario mientras esté desactualizado.

HUD y scoreboard

Durante la carrera, el sidebar muestra el top 10 en vivo y la ActionBar muestra tu vuelta, checkpoints, pits y tiempo. Se crean al empezar y se limpian al parar o resetear. Los nombres largos se truncan y el propio jugador se resalta en verde.

  • Sidebar: racing.ui.scoreboard.show-position, show-lap, show-checkpoints, show-pitstops y show-name.
  • ActionBar: racing.ui.actionbar.show-lap, show-checkpoints, show-pitstops y show-time.
  • Pits: si mandatory-pitstops > 0, aparecen PIT A/B en el sidebar y Pit A/B en la ActionBar, sujetos a los toggles.
  • Parciales: al cruzar checkpoints y meta se muestran mensajes compactos con la diferencia respecto al líder de vuelta/carrera.
  • SimpleScore: BoatRacing oculta y restaura el sidebar externo durante carreras y práctica para evitar conflictos; el timer vuelve a ocultarlo periódicamente si SimpleScore intenta recuperar el control.
  • TAB: compatible como entorno de scoreboard, sin dependencia específica.
  • Rendimiento: performance.profile acepta low, balanced o high; low duplica intervalos periódicos para proteger TPS.

Administración

/boatracing admin abre el hub. Sus secciones son Teams (crear, abrir, renombrar, recolorear, añadir/quitar miembros, borrar), Players (equipo, dorsal y bote), Race (abrir/cerrar inscripción, iniciar/forzar/parar, vueltas rápidas o personalizadas, quitar inscritos y editor de checkpoints) y Tracks (crear, seleccionar, renombrar, borrar y reaplicar la pista desde disco). En Tracks, clic izquierdo selecciona, clic derecho renombra y Shift + clic derecho borra con confirmación.

ComandoQué hace
/boatracing adminAbre el panel de administración.
/boatracing admin helpMuestra la ayuda de administración.
/boatracing admin team create <nombre> [color] [primerMiembro]Crea un equipo con color y miembro inicial opcionales.
/boatracing admin team delete <team>Elimina un equipo.
/boatracing admin team rename <antiguo> <nuevo>Renombra un equipo.
/boatracing admin team color <team> <DyeColor>Cambia el color de un equipo.
/boatracing admin team add <team> <player>Añade un jugador al equipo.
/boatracing admin team remove <team> <player>Quita un jugador del equipo.
/boatracing admin player setteam <player> <equipo|none>Asigna o quita el equipo de un jugador.
/boatracing admin player setnumber <player> <1-99>Cambia el dorsal de un jugador.
/boatracing admin player setboat <player> <BoatType>Cambia el bote o balsa de un jugador.
/boatracing admin tracksAbre la GUI de pistas: crear, seleccionar, renombrar, borrar y reaplicar.
/boatracing admin language <código>Cambia el idioma en caliente y actualiza config.yml.

Tab completion. Raíz: teams, race, cosmetics, setup, admin, extensions, reload, version, debug y subcomandos de extensiones. Carrera: help, join, leave, status, vote, voteui, votestatus; con permiso, back, practice, spectate y voteopen; los administradores ven además open, start, force, stop y voteclose. Setup sugiere todos sus comandos, pistas, equipos, jugadores, índices y subcomandos de AutoTrace. Admin sugiere help, team, player, tracks y language.

Permisos

boatracing.admin concede los demás permisos mediante hijos explícitos. boatracing.* es el comodín global, pero no concede los permisos individuales de cosméticos ni boatracing.cosmetics.unlock.all.

PermisoDescripción
boatracing.*Comodín completo. Por defecto: false.
boatracing.usePermiso base de uso. Por defecto: true.
boatracing.teamsAcceso a /boatracing teams. Por defecto: true.
boatracing.statsAcceso a /boatracing stats. Por defecto: true.
boatracing.stats.othersVer estadísticas de otros jugadores. Por defecto: true.
boatracing.versionAcceso a /boatracing version. Por defecto: true.
boatracing.cosmeticsAbrir el menú de cosméticos. Por defecto: true.
boatracing.cosmetics.adminDesbloquear, revocar y listar cosméticos. Por defecto: op.
boatracing.cosmetics.trail.<id>Desbloquea una estela concreta; no lo concede boatracing.*.
boatracing.cosmetics.title.<id>Desbloquea un título concreto.
boatracing.cosmetics.effect.<id>Desbloquea un efecto de victoria concreto.
boatracing.cosmetics.sound.<id>Desbloquea un sonido de victoria concreto.
boatracing.cosmetics.checkpoint.<id>Desbloquea un efecto de checkpoint concreto.
boatracing.cosmetics.unlock.allDesbloquea todos los cosméticos; lo concede boatracing.admin, no boatracing.*.
boatracing.debugInforme /boatracing debug. Por defecto: op.
boatracing.extensionsListar y recargar extensiones. Por defecto: op.
boatracing.reloadAcceso a /boatracing reload. Por defecto: op.
boatracing.updateAvisos de actualización en el juego. Por defecto: op.
boatracing.setupSetup, wizard, selección y GUIs de pista. Por defecto: op.
boatracing.adminPanel de administración y gestión. Por defecto: op.
boatracing.admin.languageCambiar idioma sin acceso total de admin. Por defecto: op.
boatracing.race.joinEntrar en inscripciones. Por defecto: true.
boatracing.race.leaveSalir de inscripciones. Por defecto: true.
boatracing.race.backVolver a la ubicación previa al lobby. Por defecto: true.
boatracing.race.statusConsultar estado de una pista. Por defecto: true.
boatracing.race.practiceIniciar práctica individual. Por defecto: true.
boatracing.race.forfeitAbandonar una carrera activa. Por defecto: true.
boatracing.race.spectateVer carreras como espectador. Por defecto: true.
boatracing.race.voteopenAbrir votaciones de mapa. Por defecto: op; también lo conceden boatracing.race.admin y boatracing.setup.
boatracing.race.adminAbrir, iniciar, forzar, parar y cerrar votaciones. Por defecto: op.

Configuración

La configuración vive en plugins/BoatRacing/config.yml. Al subir la versión de config, BoatRacing hace copia de config.yml y tracks/ antes de fusionar claves nuevas; tus valores existentes no se sobrescriben. Los valores siguientes son los del config.yml distribuido con 26.3.

  • General: config-version, prefix, debug (off, severe, warning, info, fine, finer, finest), language (por defecto en) y max-members-per-team (por defecto 2).
  • Economía de carrera: race.economy.enabled (false), entry-fee (0.0), refund-on-cancel (true), prizes.1 (100.0), prizes.2 (50.0), prizes.3 (25.0).
  • Rendimiento: performance.profile (low, balanced, high; por defecto balanced).
  • Acciones de jugador: player-actions.allow-team-create (true), allow-team-rename (false), allow-team-color (false), allow-team-disband (false), allow-set-boat (true), allow-set-number (true), allow-player-race-start (false).
  • Visualizador de selección: setup.selection-visualizer.enabled (true), show-only-with-wand (true), period-ticks (10), particle (END_ROD), spacing (1.0), max-particles-per-player (250), view-distance (96.0).
  • AutoTrace: setup.auto-trace.enabled (true), sample-ticks (2), min-distance (0.30), max-samples (6000), simplify-epsilon (0.4), spacing (3.0), half-width (4.5), half-height (3.0), auto-close-distance (6.0), auto-close-min-length (30.0), recenter-ice (true), start-marker (true), actionbar (true), reminder-seconds (15), preview (true), preview-period-ticks (10), preview-particle (END_ROD), preview-view-distance (96.0), wand-select (true), wand-select-radius (4.0), selection-particle (VILLAGER_HAPPY).
  • Puertas: setup.gates.half-width (4.5), half-height (3.0), finish-half-depth (0.6), checkpoint-particle (DUST), finish-particle (FLAME), preview (true), preview-period-ticks (8), view-distance (96.0), checkpoint-color (3B82F6), finish-color (FACC15).
  • Base de datos: database.mode (SQLITE), migrate-legacy-yaml (true), table (boatracing_data), sqlite.file (boatracing.db), mysql.host/port/database/username/password/parameters.
  • Práctica: practice.ghost.enabled (true), only-in-practice (true), sample-ticks (2), playback-ticks (1), min-distance (0.20), max-samples (6000), show-name (true).
  • Replay, métricas y updates: replay.capture-race (true), bstats.enabled (true), updates.enabled (true), updates.console-warn (true), updates.notify-admins (true).
  • Discord: discord.enabled (false), webhook-url, username (BoatRacing), avatar-url, discord.events.race-start (true), race-results (true), record-broken (true).
  • API: api.enabled (true), api.log-extensions (false).
  • Cosméticos: cosmetics.enabled (true), unsupported (hide), density.enabled (true), density.default (normal), density.low/normal/high (1/2/4), density.max-victory-rockets (3).
  • Estelas: cosmetics.trails.enabled (true), period-ticks (2), show-in (race-and-practice), disabled ([]), custom.<id> (particle, material, count, spread, extra, permission, enabled).
  • Efectos, sonidos y checkpoints: cosmetics.effects.enabled, effects.locked; victory-sounds.enabled, victory-sounds.locked; checkpoints.enabled, checkpoints.locked. Los ids bloqueados requieren boatracing.cosmetics.effect.<id>, .sound.<id> o .checkpoint.<id>.
  • Títulos: cosmetics.titles.enabled (true) y titles.thresholds.<id> (rookie 0, pro 5, elite 25, legend 100).
  • Tienda: cosmetics.shop.enabled (true), gated-by-default (true), require-vault (true), currency-name (coins), default-price (-1) y prices.<categoría>.<id> (0 gratis, positivo precio, no definido solo permisos).
  • Carrera: racing.laps (3), mandatory-pitstops (0), pit-penalty-seconds (5.0), registration-seconds (300), min-players-to-start (1), broadcast-mode (global; racers limita a participantes salvo inscripción), false-start-penalty-seconds (3.0), enable-pit-penalty (true), enable-false-start-penalty (true), lights-out-delay-seconds (1.0), lights-out-jitter-seconds (0.0).
  • Lobby: racing.lobby.enabled (false), return-on-leave (true), return-after-end (false), back-window-seconds (180), world, x, y, z, yaw, pitch.
  • Espectadores y victoria: racing.spectate-on-finish.mode (off, free, follow), follow-interval-ticks (10); victory-effects.enabled (true), top-n (3), screen-title, fireworks, sounds.
  • Recompensas: racing.rewards.enabled (false) y positions.<puesto>.commands|messages|broadcast; se acepta command singular heredado.
  • Mensajes: el anuncio de inscripción vive en messages_<idioma>.yml bajo race.registration.announce y admite {track}, {laps}, {cmd} y {label}. El aviso de jugadores insuficientes usa race.not-enough-players con {min} y {current}.
  • Overrides por pista: tracks/<pista>.yml puede sobrescribir racing.laps, mandatory-pitstops, registration-seconds, penalizaciones, min-players-to-start, allow-player-start, broadcast-mode, cosmetics-enabled, lobby.* y rewards.*. setup show imprime los overrides activos.

Almacenamiento

BoatRacing usa una capa DocumentStore con tres backends: SQLITE (por defecto, plugins/BoatRacing/boatracing.db, tabla boatracing_data), MYSQL (base externa para compartir datos entre servidores) y YAML (un archivo por documento). migrate-legacy-yaml: true importa los YAML antiguos en la primera carga.

  • teams.yml: miembros, colores, nombres y líder actual.
  • racers.yml: dorsales y tipos de bote por jugador.
  • stats.yml: victorias de jugador y equipo, mejor carrera y mejor vuelta.
  • practice-stats.yml: mejor/última vuelta, run y parciales de práctica.
  • practice-ghosts.yml: ghost de práctica y replay de carrera por pista y vueltas.
  • player-prefs.yml: estela, título, efecto y sonido de victoria, efecto de checkpoint y densidad.
  • cosmetic-unlocks.yml: desbloqueos y compras, con expiración opcional.
  • tracks/<pista>.yml: salidas, meta, pits, team pits, checkpoints, luces, slots, récords, overrides y datos de extensiones.

Con SQLite o MySQL, esos nombres son claves de documento dentro de la base de datos, no archivos separados; tracks/ sigue siendo siempre YAML. La tabla se valida para evitar inyección SQL por identificadores. Si un track.yml antiguo existe, se migra a tracks/default.yml (o default_N.yml) y se avisa a los administradores.

Placeholders

Con PlaceholderAPI instalado, BoatRacing registra %boatracing_*% para scoreboards, hologramas, NPCs y displays. Los textos que faltan suelen devolver -; los numéricos, 0 o -1 según el placeholder. %boatracing_player_*% usa al espectador como contexto; %boatracing_player_*_<jugador>% usa un nombre o UUID explícito y es el formato para NPCs y hologramas estáticos.

  • <pista> admite guiones bajos por espacios (My_Track). <team> usa el token del equipo y también admite guiones bajos.
  • Los placeholders de líder resuelven siempre al líder guardado actual.
  • Los de carrera por pista resuelven contra la sesión de esa pista; los globales (race_running, race_registering, race_status) reaccionan a cualquier pista.
  • race_status devuelve running si hay alguna carrera, si no registering si hay inscripción, si no idle; la etiqueta se traduce desde placeholder.race-status.*.
  • Las pistas sin sesión activa devuelven false o idle. Los alias track_racerunning, track_raceregistering y track_practicerunning siguen disponibles.

Jugador y equipo (contexto del espectador)

PlaceholderQué devuelve
%boatracing_player_name%Nombre del jugador que ve el placeholder.
%boatracing_player_team_name%, %boatracing_player_team_id%, %boatracing_player_team_color%Identidad del equipo del jugador.
%boatracing_player_team_leader_name%, %boatracing_player_team_leader_id%Líder actual del equipo del jugador.
%boatracing_player_team_players%, %boatracing_player_team_player_count%Miembros y tamaño del equipo.
%boatracing_player_number%, %boatracing_player_boat%Dorsal y bote elegido.
%boatracing_title%, %boatracing_title_id%Título equipado o automático y su id.
%boatracing_title_wins%Victorias usadas para desbloquear títulos.
%boatracing_trail%Id de la estela equipada; vacío si no hay.
%boatracing_particle_density%Densidad de partículas del jugador.
%boatracing_cosmetic_owned_<category>_<id>%true si el jugador posee ese cosmético.
%boatracing_cosmetic_expires_<category>_<id>%Epoch en milisegundos; 0 permanente, -1 sin concesión.

Estado de carrera en vivo

PlaceholderQué devuelve
%boatracing_player_race_running%, %boatracing_player_race_registering%Si el jugador está corriendo o inscrito en su propia sesión.
%boatracing_player_practice_running%Si el jugador está en práctica individual.
%boatracing_track_race_running_<track>%, %boatracing_track_race_registering_<track>%, %boatracing_track_race_status_<track>%Estado de carrera de una pista concreta (running, registering, idle).
%boatracing_race_running%, %boatracing_race_registering%, %boatracing_race_status%Estado global de cualquier pista; status devuelve running, registering o idle.
%boatracing_track_racerunning_<track>%, %boatracing_track_raceregistering_<track>%Alias compatibles de los booleanos por pista.
%boatracing_track_practice_running_<track>%, %boatracing_track_practicerunning_<track>%Práctica activa o en cuenta atrás en una pista.
%boatracing_player_current_time%, %boatracing_player_current_time_ms%Cronómetro en vivo y su valor en milisegundos.
%boatracing_player_current_lap%, %boatracing_player_current_checkpoint%Vuelta actual y siguiente checkpoint.
%boatracing_player_current_position%, %boatracing_player_current_pitstops%, %boatracing_player_finished%Posición, paradas realizadas y estado de meta.

Estadísticas de práctica

PlaceholderQué devuelve
%boatracing_player_practice_best_run%, %boatracing_player_practice_best_run_ms%Mejor vuelta completa de práctica en la pista actual.
%boatracing_player_practice_last_run%, %boatracing_player_practice_last_run_ms%Última vuelta completa de práctica.
%boatracing_player_practice_best_lap%, %boatracing_player_practice_best_lap_ms%Mejor vuelta de práctica en la pista actual.
%boatracing_player_practice_last_lap%, %boatracing_player_practice_last_lap_ms%Última vuelta de práctica.
%boatracing_player_practice_best_sector_<section>%, %boatracing_player_practice_best_sector_ms_<section>%Mejor parcial de un sector.
%boatracing_player_practice_last_sector_<section>%, %boatracing_player_practice_last_sector_ms_<section>%Último parcial de un sector.
%boatracing_player_practice_best_run_<track>%, %boatracing_player_practice_best_run_ms_<track>%Mejor vuelta completa en una pista concreta.
%boatracing_player_practice_last_run_<track>%, %boatracing_player_practice_last_run_ms_<track>%Última vuelta completa en una pista concreta.
%boatracing_player_practice_best_lap_<track>%, %boatracing_player_practice_best_lap_ms_<track>%Mejor vuelta en una pista concreta.
%boatracing_player_practice_last_lap_<track>%, %boatracing_player_practice_last_lap_ms_<track>%Última vuelta en una pista concreta.
%boatracing_player_practice_best_sector_<track>_<section>%, %boatracing_player_practice_best_sector_ms_<track>_<section>%Mejor parcial de sector en una pista concreta.
%boatracing_player_practice_last_sector_<track>_<section>%, %boatracing_player_practice_last_sector_ms_<track>_<section>%Último parcial de sector en una pista concreta.

Récords y victorias del espectador

PlaceholderQué devuelve
%boatracing_player_track_best%, %boatracing_player_track_best_ms%Mejor tiempo del jugador en la pista actual.
%boatracing_player_best_race%, %boatracing_player_best_race_ms%Mejor carrera global del jugador.
%boatracing_player_best_race_track_<track>%, %boatracing_player_best_race_ms_track_<track>%Mejor carrera del jugador en una pista.
%boatracing_player_best_race_laps_<track>_<laps>%, %boatracing_player_best_race_ms_laps_<track>_<laps>%Mejor carrera para pista y número de vueltas.
%boatracing_player_best_lap%, %boatracing_player_best_lap_ms%Mejor vuelta global del jugador.
%boatracing_player_best_lap_track_<track>%, %boatracing_player_best_lap_ms_track_<track>%Mejor vuelta del jugador en una pista.
%boatracing_player_best_lap_laps_<track>_<laps>%, %boatracing_player_best_lap_ms_laps_<track>_<laps>%Mejor vuelta para pista y contexto de vueltas.
%boatracing_player_wins%, %boatracing_player_team_wins%Victorias del jugador y de su equipo.

Globales, top y récords de pista

PlaceholderQué devuelve
%boatracing_teams_count%, %boatracing_teams_list%Número total de equipos y lista de equipos.
%boatracing_track_name%, %boatracing_track_best_player%, %boatracing_track_best_time%Pista actual y su récord.
%boatracing_track_best_player_<track>%, %boatracing_track_best_time_<track>%, %boatracing_track_best_time_ms_<track>%Récord de una pista concreta.
%boatracing_track_best_player_laps_<track>_<laps>%, %boatracing_track_best_time_laps_<track>_<laps>%, %boatracing_track_best_time_ms_laps_<track>_<laps>%Récord de pista para un número de vueltas.
%boatracing_track_top_1_player_<track>%, %boatracing_track_top_1_time_<track>%, %boatracing_track_top_1_time_ms_<track>%Primer puesto del top por pista.
%boatracing_track_top_2_player_<track>%, %boatracing_track_top_2_time_<track>%, %boatracing_track_top_2_time_ms_<track>%Segundo puesto del top por pista.
%boatracing_track_top_3_player_<track>%, %boatracing_track_top_3_time_<track>%, %boatracing_track_top_3_time_ms_<track>%Tercer puesto del top por pista.
%boatracing_track_top_1|2|3_player_laps_<track>_<laps>%, %boatracing_track_top_1|2|3_time_laps_<track>_<laps>%, %boatracing_track_top_1|2|3_time_ms_laps_<track>_<laps>%Podio por pista y número de vueltas; se aplica el mismo patrón a top 1, 2 y 3.
%boatracing_top_player_wins_name%, %boatracing_top_player_wins%Jugador con más victorias y total.
%boatracing_top_team_wins_name%, %boatracing_top_team_wins%Equipo con más victorias y total.
%boatracing_top_player_best_race_name%, %boatracing_top_player_best_race%Récord global de carrera.
%boatracing_top_player_best_race_name_track_<track>%, %boatracing_top_player_best_race_track_<track>%Récord de carrera en una pista.
%boatracing_top_player_best_race_name_laps_<track>_<laps>%, %boatracing_top_player_best_race_laps_<track>_<laps>%Récord de carrera para pista y vueltas.
%boatracing_top_player_best_lap_name%, %boatracing_top_player_best_lap%Récord global de vuelta.
%boatracing_top_player_best_lap_name_track_<track>%, %boatracing_top_player_best_lap_track_<track>%Récord de vuelta en una pista.
%boatracing_top_player_best_lap_name_laps_<track>_<laps>%, %boatracing_top_player_best_lap_laps_<track>_<laps>%Récord de vuelta para pista y vueltas.

Equipo por nombre

PlaceholderQué devuelve
%boatracing_team_leader_name_<team>%, %boatracing_team_leader_id_<team>%Líder actual de un equipo concreto.
%boatracing_team_players_<team>%Lista de jugadores del equipo.
%boatracing_team_player_count_<team>%Número de miembros del equipo.
%boatracing_team_wins_<team>%Victorias del equipo.

Jugador por nombre o UUID

PlaceholderQué devuelve
%boatracing_player_name_<player>%Nombre del jugador objetivo.
%boatracing_player_wins_<player>%Victorias del jugador objetivo.
%boatracing_player_best_race_<player>%, %boatracing_player_best_race_ms_<player>%Mejor carrera del jugador objetivo.
%boatracing_player_best_lap_<player>%, %boatracing_player_best_lap_ms_<player>%Mejor vuelta del jugador objetivo.
%boatracing_player_track_best_<player>%, %boatracing_player_track_best_ms_<player>%Mejor tiempo del jugador en la pista actual.
%boatracing_player_team_name_<player>%, %boatracing_player_team_id_<player>%, %boatracing_player_team_color_<player>%Equipo del jugador objetivo.
%boatracing_player_team_leader_name_<player>%, %boatracing_player_team_leader_id_<player>%Líder del equipo del jugador objetivo.
%boatracing_player_team_wins_<player>%Victorias del equipo del jugador objetivo.
%boatracing_player_number_<player>%, %boatracing_player_boat_<player>%Dorsal y bote del jugador objetivo.

API y extensiones

BoatRacing expone una API pequeña y estable para que otros plugins o addons se enganchen a las carreras sin tocar internals. La base funciona igual con o sin extensiones. El contrato público está en es.jaie55.boatracing.api y sus subpaquetes .event y .extension; el resto es interno.

  • Entrada: BoatRacingProvider + BoatRacingAPI, registrados con Bukkit ServicesManager. api.enabled (true) y api.log-extensions (false).
  • Eventos: RaceOpenEvent, RaceJoinEvent, RaceLeaveEvent, RaceStartEvent, CheckpointReachedEvent, LapCompleteEvent, PitStopEvent, RaceFinishEvent, RaceStopEvent, RaceForfeitEvent, PracticeStartEvent y PracticeFinishEvent.
  • Vistas: RaceSessionView y PlayerRaceView ofrecen vuelta, checkpoint, posición, tiempo transcurrido/final, estado, participantes y audiencia.
  • Seguridad: los eventos corren en el hilo principal dentro de try/catch; una extensión rota no rompe la carrera. apiVersion() protege la compatibilidad.
  • HUD: HudProvider permite añadir líneas al sidebar y un sufijo a la ActionBar; BoatRacing mantiene el control del HUD.
  • Placeholders de extensión: registerPlaceholder expone %boatracing_<identifier>%; el addon de party añade %boatracing_party_points%, %boatracing_party_item%, %boatracing_party_top1_name% y %boatracing_party_top1_points%.
  • Helpers externos: BoatRacingProvider.isCompatible(), sessions(), sessionForTrack(), sessionForPlayer(), isRacing() y pluginVersion(); un plugin externo usa depend: [BoatRacing] en su plugin.yml.

Extensiones gestionadas por la base. Se cargan desde plugins/BoatRacing/extensions/; cada jar necesita extension.yml (name, main, version, api-version) y una clase principal que implemente BoatRacingExtension. No son plugins Bukkit. BoatRacing crea una carpeta extensions/<name>/ con config.yml, lang/ y almacenamiento, y expone ExtensionContext con configuración, mensajes, storage, scheduler Folia-aware, listeners, comandos, HUD, placeholders y datos por pista. Se gestionan con /boatracing extensions y reload; debug las lista.

Ciclo de vida: onEnable(ExtensionContext), onDisable() y onReload(); en onReload la configuración y los mensajes ya están refrescados. Los comandos se registran bajo /boatracing <nombre> o /boatracing setup <nombre> y las excepciones se capturan para que una extensión rota no rompa la carrera.

BoatRacing-PartyExtension (addon privado). Vive en party/ del repositorio local y se instala como extensión gestionada. Añade habilidades tipo party (Mushroom, Banana, Green Shell, Lightning, Super Star, Blooper, Coin, Bob-omb), cajas de objetos por pista, puntos de party, HUD y placeholders. Se activa abriendo la carrera con /boatracing race open <pista> party; las carreras normales ignoran por completo el addon. Sus comandos son /boatracing party help|points [jugador]|top|reload y los setup boxmarker, addbox, boxes, delbox, clearboxes, previewboxes y boxinfo. Los objetos salen al inicio, por probabilidad al cruzar checkpoints y de las cajas; los permisos son boatracing.party.use (true) y boatracing.party.admin (op); se compila con scripts/build-all.ps1 y se omite si api-version es más nueva que la API instalada. Su config y mensajes están en plugins/BoatRacing/extensions/BoatRacing-PartyExtension/.

Desarrollar extensiones

Hay dos modelos: extensión gestionada (recomendada para addons; BoatRacing la carga y le da config, idioma, storage, scheduler, comandos, HUD y placeholders) o plugin externo (plugin Bukkit con depend: [BoatRacing] que lee la API por BoatRacingProvider).

<repositories>
  <repository>
    <id>papermc-repo</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.papermc.paper</groupId>
    <artifactId>paper-api</artifactId>
    <version>1.19.4-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>es.jaie55</groupId>
    <artifactId>boatracing</artifactId>
    <version>26.3</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Instala el artefacto local con mvnw.cmd -q -DskipTests clean install o scripts/build-all.ps1 y compila con release 17. El descriptor extension.yml va en la raíz del jar:

name: MyExtension
main: com.example.MyExtension
version: '26.3'
api-version: 1
description: What your extension does.
authors: [YourName]
  • name se convierte en plugins/BoatRacing/extensions/MyExtension/.
  • version debería coincidir con BoatRacing; una diferencia solo avisa. api-version debe ser <= BoatRacingAPI.API_VERSION o el jar se omite.
  • main debe implementar BoatRacingExtension con constructor público sin argumentos.
  • config.yml y lang/messages_*.yml del jar se copian a la carpeta de la extensión en la primera carga.

Contexto disponible: config()/reloadConfig(), message()/messageList()/language(), storage(), scheduler(), api(), registerCommand(), registerSetupCommand(), selectedTrackName(), selectedTrackData()/setSelectedTrackData(), trackData()/setTrackData()/removeTrackData(), registerListener(), registerHudProvider() y registerPlaceholder().

Comandos: implementan ExtensionCommand con name(), permission(), allowConsole(), usage(), execute() y tabComplete(); args llega después del nombre del subcomando. Eventos: los mismos que la API externa, todos informativos, en hilo principal y no cancelables. Build: empaqueta el jar, cópialo a plugins/BoatRacing/extensions/ y comprueba la carga con /boatracing extensions; debug: "fine" traza fallos.

Buenas prácticas: no bloquees el hilo principal, mantén los HUD providers baratos (se llaman cada 2 ticks), limpia lo que generes en RaceStopEvent/onDisable, persiste solo con storage() y no intentes saltarte checkpoints, vueltas, pits o resultados.

Diagnóstico, updates y build

  • /boatracing debug (solo admin, boatracing.debug) imprime versión del plugin, servidor, API, Java, almacenamiento, idioma, nivel de debug y conteos de pistas/equipos/sesiones. Nunca incluye contraseñas de base de datos ni URLs de webhook.
  • El destino de errores es fijo: GitHub Issues. Adjunta el informe y logs/latest.log.
  • Para trazas detalladas usa debug: "fine", "finer" o "finest"; AutoTrace, cosméticos, Discord, espectadores, efectos y replay escriben logs con esos niveles.
  • Updates: fuente Modrinth, comprobación silenciosa cada 5 minutos, WARN al detectar una versión nueva, recordatorio horario mientras esté desactualizado y aviso en el juego a quien tenga boatracing.update.
  • bStats: activo por defecto, ID 26881; se desactiva con bstats.enabled: false.
  • Build: proyecto Maven; mvn -DskipTests clean package genera el BoatRacing.jar sombreado. La licencia es MIT; consulta LICENSE.

Notas y límites

  • Los equipos pueden tener varios miembros y un líder guardado; si el líder sale, la jefatura pasa al siguiente miembro y el último miembro que sale disuelve el equipo.
  • Los textos de usuario viven en messages_<idioma>.yml y se recargan con /boatracing reload; los identificadores de idioma personalizados se seleccionan con language.
  • Cruzar una puerta en sentido contrario cuenta: la dirección no se comprueba, el orden de checkpoints es la protección contra atajos.
  • No hay teleport ni penalización por salir de la ruta; si llegas a meta sin todos los checkpoints, la vuelta se rechaza y debes volver.
  • Las puertas no tienen colisión y solo se dibuja su contorno; no son zonas de permanencia.
  • El pit es la única área real: cuenta paradas, aplica penalización y puede bloquear la meta si hay paradas obligatorias.
  • La detección de checkpoint y meta es segmento-plano/rayo-AABB, así que los botes de hielo rápidos no se saltan las puertas entre ticks.
  • El lobby guarda la ubicación previa en memoria durante back-window-seconds (180 por defecto); después /boatracing race back expira para ese ciclo.
  • Las extensiones pueden añadir datos a tracks/<pista>.yml bajo extensions.<extension> para que viajen con la pista.
  • Esta página cubre la referencia pública 26.3; para cambios históricos consulta el CHANGELOG.md del repositorio.