Configurar Adventure-Platform para Textos Ricos en Minecraft

Si has creado plugins o software de servidor para Minecraft, probablemente hayas sentido las dificultades del formato de texto. Colores, estilos, eventos de clic, texto flotante - todo es específico de la plataforma. Paper lo maneja de una forma, BungeeCord de otra, Sponge de otra más. Adventure-Platform resuelve esto proporcionándote una API unificada para componentes de texto que funciona en todas ellas.

Qué hace Adventure-Platform

Adventure-Platform es un conjunto de implementaciones que se sitúan sobre la biblioteca Adventure, una biblioteca de componentes de texto creada por Kyori. Piensa en Adventure como el lenguaje común, y Adventure-Platform como el traductor para diferentes plataformas Minecraft.

Por sí sola, Adventure es agnóstica de plataforma - no sabe nada sobre el formato NBT de Paper ni sobre los arreglos de bytes de BungeeCord. Solo proporciona APIs Java limpias. ¿Pero tu software de servidor? Necesita componentes de texto nativos. Ahí es donde Adventure-Platform entra en juego. Envuelve implementaciones específicas de plataforma en una única interfaz limpia.

Soporta Paper, Spigot y Bukkit en el lado del servidor. Maneja proxies BungeeCord. Incluso cubre Sponge si te interesa. La última versión añadió soporte para Minecraft 1.21.6 y 1.21.7.

Por qué los desarrolladores de servidores usan esto

Digamos que estás escribiendo un plugin que necesita un mensaje de entrada personalizado con colores, eventos de clic y tooltips flotantes. Sin Adventure-Platform, escribirías una versión para Bukkit, otra para Sponge, quizás una tercera para Velocity. No es divertido.

Con Adventure-Platform, lo escribes una sola vez. La biblioteca descubre en qué plataforma estás y traduce tus componentes automáticamente. Colores, degradados, ofuscación, tachado - todo manejado. Los eventos de clic (abrir URL, ejecutar comando, copiar al portapapeles, mostrar texto) funcionan en todas las plataformas.

Ejemplo del mundo real: estás creando un MOTD (mensaje del día) del servidor. Usando Adventure, creas un componente de texto con colores y texto flotante. Adventure-Platform convierte eso a cualquier formato que tu servidor entienda. Si cambias de Paper a BungeeCord más tarde, tu código permanece igual.

Esto es genuinamente útil si estás manteniendo un plugin o software de servidor que apunta a múltiples plataformas.

Integrando Adventure-Platform en tu Proyecto

Primero, necesitarás añadir la dependencia. Los artefactos de Adventure-Platform se encuentran en Maven Central. Así es cómo lo configurarías en un archivo de compilación Gradle:

repositories {
 mavenCentral()
}

dependencies {
 // Para servidores basados en Bukkit (Paper, Spigot, Craftbukkit)
 implementation "net.kyori:adventure-platform-bukkit:4.4.1"

 // Para BungeeCord
 // implementation "net.kyori:adventure-platform-bungeecord:4.4.1"

 // Para Sponge API 7
 // implementation "net.kyori:adventure-platform-sponge7:4.4.1"
}

Elige el artefacto correcto para tu plataforma. Si estás usando Maven en su lugar, las coordenadas son las mismas, solo en sintaxis XML de Maven.

Una vez que hayas añadido la dependencia, necesitas obtener un Audience de Adventure para tu servidor:

import net.kyori.adventure.audience.Audience;
import net.kyori.adventure.platform.bukkit.BukkitAudiences;
import net.kyori.adventure.text.Component;
import net.kyori.adventure.text.format.NamedTextColor;

public class MyPlugin extends JavaPlugin {
 private BukkitAudiences audiences;

 @Override
 public void onEnable() {
 this.audiences = BukkitAudiences.create(this);
 }

 @Override
 public void onDisable() {
 if (this.audiences!= null) {
 this.audiences.close();
 }
 }

 public void sendMessage(Player player) {
 Audience audience = this.audiences.player(player);
 Component message = Component.text("Hello, ", NamedTextColor.GOLD).append(Component.text(player.getName(), NamedTextColor.YELLOW));
 audience.sendMessage(message);
 }
}

Ese es el patrón básico. Crea tu objeto Audiences una vez en onEnable(), ciérralo en onDisable(), luego úsalo para enviar componentes a los jugadores.

Qué puedes hacer con esto

Colores de texto en los 16 colores heredados más soporte RGB completo. Minecraft 1.16+ te permite usar cualquier valor de color que desees, y Adventure maneja la conversión en versiones anteriores.

Los estilos de texto funcionan como esperarías: negrita, cursiva, subrayado, tachado, ofuscado. Combínalos de cualquier forma. Construye texto con degradado, donde los colores cambian a lo largo del mensaje.

Los eventos de clic hacen tus mensajes interactivos. Los jugadores pueden hacer clic para abrir URLs, ejecutar comandos, copiar al portapapeles o mostrar un mensaje de tooltip. Los eventos flotantes muestran texto cuando los jugadores pasan el ratón sobre un componente - perfecto para tooltips o explicaciones. Si estás creando algo como un MOTD personalizado, puedes agregar funcionalidad de hacer clic para unirse o texto flotante decorativo. Si estás creando algo como un MOTD personalizado, puedes agregar funcionalidad de hacer clic para unirse o texto flotante decorativo.

Las traducciones están incorporadas. Adventure tiene un tipo de componente traducible que maneja las claves de traducción incorporadas de Minecraft además de las personalizadas. El servidor maneja la negociación de idioma automáticamente.

La serialización JSON funciona si necesitas almacenar componentes o enviarlos a través de la red. Mira, la biblioteca puede convertir componentes a y desde JSON, siguiendo el formato nativo de Minecraft.

Trampas y qué puede causar problemas

El error más grande: no cerrar tu objeto Audiences. Mantiene recursos. Si creas un BukkitAudiences o similar y no lo cierras cuando tu plugin se desactiva, estás teniendo una fuga de memoria. Siempre cierra en onDisable().

La serialización de componentes varía entre versiones. En realidad, eso no es del todo preciso - la serialización en sí es estable, pero el formato NBT interno que Minecraft usa cambió en 1.21.6. La última versión de Adventure-Platform maneja esto, pero si estás en una versión anterior y saltas a 1.21.6, podrías ver un comportamiento extraño con componentes almacenados existentes. Esto importa si estás almacenando componentes en caché o guardándolos en bases de datos.

No asumas que todas las plataformas soportan todas las características por igual. Por ejemplo, algunas implementaciones más antiguas de Sponge podrían tener soporte limitado para características de texto más nuevas. Verifica la documentación específica de la plataforma en el sitio de documentación de Adventure antes de confiar en formato de casos límite.

Los colores RGB necesitan 1.16+. Si estás apuntando a servidores más antiguos, mantente con los colores nombrados o usa reducción de color (que Adventure puede hacer, pero necesitas manejarlo adecuadamente).

Qué más hay disponible

MiniMessage es un lenguaje de componentes basado en cadenas que funciona junto con Adventure. En lugar de construir componentes en código, puedes escribirlos en un formato legible para humanos: "¡Hola!". Es más ligero si estás construyendo texto desde archivos de configuración o entrada del usuario. MiniMessage y Adventure funcionan bien juntos.

Si no estás listo para una biblioteca completa como Adventure, existen LegacyChat u otras alternativas más simples. Manejan lo básico (colores, formato) sin la complejidad. El compromiso es que no obtienes eventos de clic, flotantes, traducciones o abstracción de plataforma. Bien para proyectos pequeños. No es bueno si necesitas características más allá de colores simples.

Algunas plataformas incluyen sus propias APIs de texto. Sponge tiene su propia implementación de texto que es similar a Adventure pero no idéntica. Waterfall (el proxy sucesor de Velocity) fomenta el uso de Adventure. Si estás construyendo para una plataforma específica y no planeas soportar múltiples servidores, podrías saltarte Adventure completamente y usar la API nativa. Pero si hay alguna posibilidad de que necesites reutilizar código o soportar múltiples plataformas más tarde, Adventure-Platform vale la inversión inicial.

¿Vale la pena configurar esto?

Sí, si estás escribiendo un plugin o software de servidor que podría terminar en múltiples tipos de plataforma o si deseas que tu código sea reutilizable. La configuración es sencilla, la API es limpia, y evitas un montón de dolores de cabeza en el camino.

Si estás desarrollando en solitario un pequeño plugin para una versión y plataforma de servidor específica, podrías no necesitarlo. Pero en el momento que pienses "¿y si quiero usar esto en un tipo de servidor diferente?" o "¿y si alguien me pide ejecutar esto en su servidor Sponge?" Adventure-Platform te ahorra una reescritura.

La biblioteca ha existido durante años y se mantiene activamente (en el momento de escribir esto, actualizaciones recientes añadieron soporte 1.21.6/1.21.7). Es usada por software de servidor y plugins principales. No es una apuesta arriesgada.