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