Ping Query Protocol – For Server Lists

PingProtocol – Minecraft Server List Ping for Hytale

Un plugin de Hytale que implementa el protocolo de Ping de la lista de servidores de Minecraft, permitiendo que los clientes de Minecraft consulten la información de tu servidor de Hytale y la muestren en su lista de servidores.

Cómo Funciona

Este plugin crea un servidor TCP que se ejecuta junto al servidor de juego QUIC (UDP) de Hytale. La clave es que TCP y UDP son protocolos separados, por lo que ambos pueden escuchar en el mismo número de puerto sin conflictos:

• Servidor de Hytale: Utiliza el protocolo UDP/QUIC en el puerto 5520 (o el puerto configurado) para el tráfico de juego
• Plugin PingProtocol: Utiliza TCP en el mismo número de puerto para las solicitudes de ping de Minecraft

Esto permite que los clientes de Minecraft hagan ping a tu servidor de Hytale sin necesidad de redireccionamiento de puertos o configuración adicional de red.

Características

• Soporte Completo del Protocolo de Minecraft:

  • Protocolo moderno (1.7+) con respuestas de estado en JSON
  • Protocolo legado (1.6) con respuestas formateadas en §1
  • Soporte para protocolos muy antiguos (Beta 1.8 – 1.3)

• Información del Servidor Automática:

  • Conteo actual de jugadores y máximo de jugadores
  • Lista de jugadores con nombres y UUIDs
  • Versión del servidor del manifiesto de Hytale (por ejemplo, “2026.01.13”)

• Optimización del Rendimiento:

  • Almacenamiento en caché de respuestas inteligente (duración de caché de 1 segundo)
  • La caché se invalida cuando cambia el conteo de jugadores
  • Tiempo de respuesta inferior a 10 ms para solicitudes en caché

• Configuración Sencilla:

  • Texto MOTD personalizado
  • Mostrar/ocultar lista de jugadores
  • Siempre utiliza el puerto del servidor de juego (no se necesita configuración adicional)

Instalación

• Descarga PingProtocol-1.0.0.jar de las versiones
• Colócalo en el directorio mods/ de tu servidor de Hytale
• Inicia tu servidor o escribe /plugin load Hytalist:PingProtocol
• Configura en mods/Hytalist_PingProtocol/config.json si es necesario

Configuración

El plugin crea un archivo config.json en mods/Hytalist_PingProtocol/:

{
  "motd": "",
  "showPlayerList": true
}

Opciones de Configuración

Opción	Por Defecto	Descripción
motd	""	Mensaje del Día mostrado a los clientes de Minecraft (cadena vacía si no está configurado)
showPlayerList	true	Mostrar lista de jugadores al pasar el ratón sobre el conteo de jugadores

El plugin automáticamente:

• Utiliza el mismo puerto que tu servidor de Hytale (TCP/UDP pueden compartir el mismo puerto)
• Informa la versión del protocolo 0 para indicar que no es un servidor de Minecraft
• Lee la versión del servidor del manifiesto de Hytale y elimina el hash de compilación (por ejemplo, “2026.01.13-dcad8778f” se convierte en “2026.01.13”)

Soporte de Protocolo

Protocolo Moderno (Minecraft 1.7+)

El plugin implementa el protocolo completo de Ping de la lista de servidores moderno:

• Paquete de Handshake (0x00): El cliente envía la versión del protocolo, dirección del servidor, puerto y estado siguiente
• Solicitud de Estado (0x00): El cliente solicita el estado del servidor
• Respuesta de Estado (0x00): El servidor envía JSON con versión, jugadores, descripción
• Solicitud de Ping (0x01): El cliente envía una marca de tiempo
• Respuesta Pong (0x01): El servidor repite la marca de tiempo y cierra la conexión

Ejemplo de respuesta JSON:

{
  "version": {
    "name": "2026.01.13",
    "protocol": 0
  },
  "players": {
    "max": 100,
    "online": 5,
    "sample": [
      {
        "name": "PlayerName",
        "id": "uuid-here"
      }
    ]
  },
  "description": {
    "text": "Mi Servidor de Hytale"
  }
}

Protocolo Legado (Minecraft 1.6)

El plugin también soporta el protocolo de ping legado para clientes más antiguos:

• Detecta los bytes mágicos 0xFE 0x01 0xFA
• Responde con el paquete de patada 0xFF
• Formato: §1protocolversionmotdonlinemax

Protocolo Muy Antiguo (Beta 1.8 – 1.3)

Soporta el protocolo de ping más antiguo:

• Detecta el byte mágico 0xFE
• Responde con el paquete de patada 0xFF
• Formato: motd§online§max

Rendimiento

El plugin está optimizado para respuestas de baja latencia:

• Almacenamiento en Caché de Respuestas: Las respuestas de estado se almacenan en caché durante 1 segundo
• Invalidación Inteligente: La caché se invalida cuando cambia el conteo de jugadores
• Tiempos de Respuesta Típicos:
  • Primera solicitud (fallo de caché): ~10-50ms
  • Solicitudes en caché: <10ms
  • La caché evita operaciones costosas como obtener la lista completa de jugadores y la serialización JSON en cada ping

Detalles Técnicos

Arquitectura

El plugin utiliza Netty (ya disponible en el servidor de Hytale) para crear un servidor TCP:

• PingServer: Inicializa y gestiona el servidor Netty
• MinecraftPingHandler: Manejador con estado que procesa paquetes
• StatusCache: Caché compartida para respuestas de estado para minimizar operaciones costosas
• MinecraftProtocol: Utilidades para codificación/decodificación de VarInt y lectura/escritura de paquetes
• StatusResponse: Clases de datos para serialización JSON

Por Qué Esto Funciona

El Ping de la lista de servidores de Minecraft utiliza TCP, mientras que Hytale utiliza QUIC que se ejecuta sobre UDP. Dado que estos son diferentes protocolos de transporte, ambos pueden enlazarse al mismo número de puerto:

• Paquetes TCP → Manejados por el plugin PingProtocol
• Paquetes UDP → Manejados por el servidor QUIC de Hytale

Esto es similar a cómo funciona el plugin HyQuery (mostrado en EXAMPLE_INTERCEPT.md), excepto que:

• HyQuery intercepta paquetes UDP antes del códec QUIC
• PingProtocol ejecuta un servidor TCP separado junto a Hytale

Construcción desde el Código Fuente

./gradlew jar

El JAR se creará en build/libs/PingProtocol-1.0.0.jar.

Resolución de Problemas

“No se pudo iniciar el servidor de ping en el puerto X”

Causa: Otro servicio TCP está utilizando el puerto

Solución:

• Verifica si otro servicio está vinculado al puerto TCP
• Asegúrate de que tu firewall permita conexiones TCP en el puerto
• Nota: El plugin utiliza el mismo número de puerto que Hytale pero en TCP (Hytale utiliza UDP)

El cliente de Minecraft muestra “No se puede conectar al servidor”

Causa: Firewall bloqueando conexiones TCP o plugin no iniciado

Solución:

• Verifica que el plugin se haya iniciado correctamente en los registros del servidor
• Comprueba que el firewall permita tráfico TCP en el puerto del servidor
• Intenta añadir el servidor utilizando el formato IP:puerto en Minecraft

Lista de jugadores no mostrada

Causa: Configuración o ningún jugador en línea

Solución:

• Establece "showPlayerList": true en la configuración
• Asegúrate de que los jugadores estén realmente en línea en el servidor de Hytale
• La lista de jugadores solo se muestra cuando currentPlayerCount > 0

Respuestas de ping lentas

Causa: Caché no funcionando o primera solicitud

Solución:

• La primera solicitud construye la caché y puede tardar de 10 a 50 ms
• Las solicitudes subsiguientes deberían ser <10 ms
• La caché se invalida cada segundo o cuando cambia el conteo de jugadores
• Si es consistentemente lenta, verifica el rendimiento del servidor de Hytale

Créditos

• Implementación basada en la especificación de Ping de la lista de servidores de Minecraft