Cómo Agregar GUIs de Yunque en tu Servidor Minecraft

Construir un plugin de Minecraft que necesita entrada del jugador es un problema común. Podrías pedirles a través del chat, pero eso inunda el registro de chat. Cualquiera podría construir una GUI de inventario personalizada, pero eso requiere texturas y código adicional. Las pantallas de yunque son perfectas para entrada de texto simple, y AnvilGUI es la biblioteca que las hace funcionar en todas las versiones de Minecraft sin tocar una línea de código NMS.

Esto es importante porque los internos de Minecraft cambian constantemente. Las GUI de yunque en la versión 1.20 se manejan completamente diferente que en 1.21. La mayoría de desarrolladores de plugins o se adhieren a su versión del servidor o usan hacks de reflexión para admitir múltiples versiones. AnvilGUI hace ese trabajo de reflexión por ti.

Qué Hace AnvilGUI

AnvilGUI es un envoltorio alrededor del inventario de yunque de Minecraft diseñado específicamente para capturar texto de los jugadores. En lugar de sumergirse en net.minecraft.server (los internos ofuscados que cambian en cada parche), escribes código de patrón constructor limpio. La biblioteca detecta qué versión estás ejecutando y carga la implementación correcta en tiempo de ejecución.

Así es como se ve en la práctica.

El flujo de trabajo principal es directo: el jugador ve una pantalla de yunque con un título y algo de texto predeterminado. Escriben algo, hacen clic en la ranura de salida (la del lado derecho), y tu código se ejecuta. Validas la entrada, cierras la pantalla o les pides que lo intenten de nuevo. Todo con manejadores de eventos.

Cuándo Usarías Esto

La entrada de texto de los jugadores aparece en todas partes en el desarrollo de plugins. Sistemas de misiones que piden nombres de personajes. Comandos de apodos personalizados. Casas de subastas donde los vendedores establecen precios. Sistemas de tienda con pujas de jugadores. Incluso herramientas de conversión de coordenadas como nuestra Calculadora de Portal del Nether necesitan interfaces de entrada limpias.

Y aquí está la cosa: las GUI de yunque se sienten nativas en Minecraft. La interfaz ya está ahí, los jugadores la entienden al instante, y no rompe la inmersión con diálogos raros o menús emergentes. Si estuvieras construyendo algo como nuestro Creador de MOTD de Minecraft (que permite a los jugadores diseñar mensajes del servidor), una entrada de yunque encajaría perfectamente en ese flujo.

Algunos plugins usan el chat para entrada, pero eso obstruye el registro de chat y se ve desordenado. Otros construyen GUI de inventario completamente personalizadas, que requieren texturas personalizadas y mucho más código. Los yunques son el punto justo: están integrados, se sienten vanilla, y AnvilGUI abstrae la pesadilla de compatibilidad de versiones.

Instalar AnvilGUI

Primero, agrega el repositorio de Maven. A partir de la versión 1.10.11, el repositorio se trasladó a una nueva URL:

<repository>
 <id>mvn-wesjd-net</id>
 <url>https://mvn.wesjd.net/</url>
</repository>

Luego agrega la dependencia:

<dependency>
 <groupId>net.wesjd</groupId>
 <artifactId>anvilgui</artifactId>
 <version>1.10.12-SNAPSHOT</version>
 <scope>compile</scope>
</dependency>

El ámbito compile significa que AnvilGUI se incluye en tu JAR final.

Ahora viene la parte que confunde a la gente: sombreado. AnvilGUI es una biblioteca, no un plugin independiente, por lo que necesitas maven-shade-plugin para incluirlo en el JAR de tu plugin. Esto evita conflictos de ruta de clase si múltiples plugins en el mismo servidor usan AnvilGUI.

<plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-shade-plugin</artifactId>
 <version>3.5.0</version>
 <executions>
 <execution>
 <phase>package</phase>
 <goals>
 <goal>shade</goal>
 </goals>
 <configuration>
 <relocations>
 <relocation>
 <pattern>net.wesjd.anvilgui</pattern>
 <shadedPattern>your.plugin.package.anvilgui</shadedPattern>
 </relocation>
 </relocations>
 </configuration>
 </execution>
 </executions>
</plugin>

Reemplaza your.plugin.package con el nombre de tu paquete actual. Esto traslada AnvilGUI a tu espacio de nombres para que no entre en conflicto con otros plugins.

Cómo Funciona la API

Aquí hay un ejemplo completo del proyecto:

new AnvilGUI.Builder().onClose(stateSnapshot -> {
 stateSnapshot.getPlayer().sendMessage("You closed the inventory.");
 }).onClick((slot, stateSnapshot) -> {
 if(slot!= AnvilGUI.Slot.OUTPUT) {
 return Collections.emptyList();
 }

 if(stateSnapshot.getText().equalsIgnoreCase("you")) {
 stateSnapshot.getPlayer().sendMessage("You've magical powers!");
 return Arrays.asList(AnvilGUI.ResponseAction.close());
 } else {
 return Arrays.asList(AnvilGUI.ResponseAction.replaceInputText("Try again"));
 }
 }).preventClose().text("What's the meaning of life?").title("Enter your answer").plugin(plugin).open(player);

El patrón constructor encadena llamadas de método. Title es el texto encima del yunque. Text es la entrada predeterminada (contenido prellenado). OnClose se activa cuando el jugador cierra sin enviar. OnClick se activa cuando hacen clic en una ranura del yunque.

El parámetro slot te dice lo que hicieron clic. Hay INPUT (ranura izquierda), OUTPUT (ranura derecha donde se muestran resultados), y RESULT (el elemento real que obtendrían si esto fuera una receta real). Casi siempre verificas OUTPUT ya que ese es el botón de envío.

StateSnapshot contiene el jugador y cualquier texto que hayan escrito. Lo validas y devuelves ResponseActions. ResponseAction.close() cierra la pantalla. ResponseAction.replaceInputText() actualiza el campo de entrada, útil para mensajes de error como "ese nombre ya está tomado" o "intenta de nuevo".

PreventClose() elimina la opción de tecla de escape, obligando a los jugadores a enviar o hacer clic en otras ranuras. Usa esto para información crítica que absolutamente necesitas de ellos.

Plugin(plugin) es la instancia de tu plugin. Se necesita para el registro de eventos y la detección de versión bajo el capó.

Una cosa más poderosa: puedes personalizar casi todo. Títulos más largos, texto de solo lectura, comportamientos de ranura diferentes según la entrada. La API te da control.

Errores Comunes y Trampas

La configuración de sombreado es la más grande. Omite maven-shade-plugin y tu plugin ni siquiera se cargará. Obtendrás ClassNotFoundException en tiempo de ejecución, y tarda un segundo darse cuenta por qué.

Otro patrón que confunde a la gente: onClick espera que devuelva una List<ResponseAction>. Una lista vacía (Collections.emptyList()) es válida y solo mantiene la pantalla abierta. El compilador detecta devoluciones faltantes de todos modos, así que esto generalmente no es un problema en la práctica.

El texto de entrada en el yunque no tiene color ni está especialmente formateado. Es solo texto. Más allá del título y contenido predeterminado, no hay mucha personalización visual disponible. Si necesitas elementos visuales más elegantes (colores personalizados, texto formateado), querrías un enfoque diferente.

Sobre la compatibilidad de versiones: AnvilGUI funciona en versiones recientes. En realidad, también funciona en versiones antiguas mediante detección de versión basada en reflexión. Consulta la página de lanzamientos si ejecutas algo realmente antiguo, pero la respuesta corta es que si tu servidor puede cargar la biblioteca, funciona.

La biblioteca no maneja la traducción de i18n por ti. Si tu servidor admite varios idiomas, estás traduciendo el título y el texto tú mismo antes de pasarlos a AnvilGUI.

Alternativas y Cuándo Usarlas

Si las pantallas de yunque no son la opción correcta, tienes otras opciones.

Las GUI de señal permiten a los jugadores escribir en una señal, luego la lees. Más simple en algunos aspectos, pero no se siente tan integrado. Los jugadores ven una señal en lugar de un yunque.

Las GUI de libro usan la interfaz de libro escribible de Minecraft. Excelente para texto más largo, pero excesivo para un solo campo de entrada. Es una interacción más pesada.

Las GUI de inventario completamente personalizadas te dan el máximo control. Botones, deslizadores, iconos, colores - lo que quieras. El intercambio es más código y texturas personalizadas. Si estás construyendo algo complejo, podría valer la pena. Para entrada de texto simple, es excesivo.

La entrada de chat siempre es técnicamente posible. Solo pide al jugador que responda en el chat o use un comando. Funciona, pero spamea el registro de chat y se siente torpe. La mayoría de los plugins modernos lo evitan.

Mi Postura Sobre Esto

AnvilGUI resuelve bien un problema específico: capturar texto de los jugadores sin luchar contra el código específico de versión de Minecraft. Es una biblioteca de Java con licencia MIT, activamente mantenida, y tiene 542 estrellas sólidas en GitHub. Si estás construyendo un plugin que necesita entrada del jugador y un yunque tiene sentido para tu caso de uso, dedica diez minutos a integrar esto. Te ahorrará del infierno de depuración de compatibilidad de versiones en el futuro.