HyQuery

# HyQuery – Protocolo de Consulta UDP para Hytale

HyQuery es un plugin de protocolo de consulta ligero basado en UDP para servidores de Hytale. Permite que las listas de servidores y las herramientas de monitorización consulten el estado de tu servidor, el número de jugadores y los metadatos sin necesidad de puertos adicionales o configuraciones complejas.

## ¿Qué es HyQuery?

HyQuery proporciona una forma simple y rápida para que los servicios externos consulten la información de tu servidor de Hytale. A diferencia de los métodos de consulta tradicionales basados en HTTPS, HyQuery utiliza paquetes UDP y se ejecuta directamente en el puerto de tu servidor de juego (típicamente 5520), eliminando la necesidad de redirigir puertos adicionales o configurar el cortafuegos.

## Características Clave

– **No se requieren puertos adicionales** – Utiliza el puerto existente de tu servidor de juego (UDP 5520)

– **Instalación de un solo plugin** – Simplemente coloca el JAR en tu carpeta de mods

– **Soporte para MOTD personalizado** – Establece un MOTD personalizado con códigos de color de Minecraft para las listas de servidores

– **Controles de privacidad** – Elige si deseas exponer las listas de jugadores y la información del plugin

– **Cero configuración** – Funciona directamente con configuraciones predeterminadas sensatas

– **Ligero** – Mínimo impacto en el rendimiento utilizando un protocolo UDP eficiente

## Cómo Funciona

HyQuery intercepta los paquetes UDP antes de que lleguen al manejador de protocolo QUIC del juego. Al comprobar si hay “bytes mágicos” especiales (`HYQUERY`) al inicio de cada paquete, HyQuery puede identificar y responder a las solicitudes de consulta mientras pasa todo el tráfico restante al servidor de juego sin cambios.

Este diseño significa:

– Sin conflictos con el tráfico del servidor de juego

– No se necesita configuración de red adicional

– Funciona sin problemas junto a tu servidor de juego

– Perfecto para entornos de alojamiento compartido

## Instalación

1. Descarga el último `hyquery-plugin-x.x.x-SNAPSHOT.jar` desde la página de lanzamientos

2. Coloca el archivo JAR en la carpeta `/mods` de tu servidor

3. Reinicia tu servidor

4. HyQuery creará automáticamente un archivo de configuración predeterminado

Después de iniciar, deberías ver mensajes de inicialización en tu consola:

“`

[INFO] HyQuery cargando…

[INFO] Cargando configuración…

[INFO] Creado archivo de configuración predeterminado en mods/Hyvote_HyQuery/config.json

[INFO] HyQuery iniciando…

[INFO] HyQuery habilitado en el puerto UDP 5520 (3 canales)

“`

## Configuración

HyQuery crea automáticamente un archivo de configuración en:

“`

mods/Hyvote_HyQuery/config.json

“`

 

### Configuración Predeterminada

 

“`json

{

  “enabled”: true,

  “showPlayerList”: false,

  “showPlugins”: false,

  “useCustomMotd”: false,

  “customMotd”: “§a¡Bienvenido a §lMi Servidor§r!”

}

“`

 

### Opciones de Configuración

 

| Opción | Tipo | Predeterminado | Descripción |

|——–|——|———|————-|

| `enabled` | booleano | `true` | Habilitar o deshabilitar el servidor de consulta |

| `showPlayerList` | booleano | `false` | Incluir nombres y UUIDs de jugadores en las respuestas de consulta |

| `showPlugins` | booleano | `false` | Incluir lista de plugins instalados en las respuestas de consulta |

| `useCustomMotd` | booleano | `false` | Usar MOTD personalizado en lugar del MOTD de configuración del servidor |

| `customMotd` | cadena | `”§a¡Bienvenido…”` | MOTD personalizado con soporte para códigos de color de Minecraft |

 

### Estableciendo un MOTD Personalizado

 

Una de las características únicas de HyQuery es la capacidad de establecer un MOTD personalizado específicamente para las listas de servidores, separado de tu MOTD en el juego:

 

“`json

{

  “enabled”: true,

  “showPlayerList”: false,

  “showPlugins”: false,

  “useCustomMotd”: true,

  “customMotd”: “§6¡Bienvenido a §l§b¡Mi Servidor Épico§r§6! §a¡Únete ahora!”

}

“`

 

**Códigos de Color de Minecraft Soportados:**

– Colores: `§0-§9`, `§a-§f` (negro, azul, verde, aqua, rojo, púrpura, oro, gris, etc.)

– Formato: `§l` (negrita), `§o` (cursiva), `§n` (subrayado), `§m` (tachado)

– Restablecer: `§r` (elimina todo formato)

 

### Configuraciones de Privacidad

 

Por defecto, HyQuery no expone los nombres de los jugadores ni la información del plugin. Habilita estas opciones si deseas mostrar:

 

“`json

{

  “showPlayerList”: true,  // Mostrar nombres y UUIDs de jugadores

  “showPlugins”: true      // Mostrar nombres de plugins instalados

}

“`

 

**Nota:** La lista de jugadores y la información del plugin solo están disponibles cuando se consulta con el tipo de consulta “completa”.

 

## Probando tu Configuración

 

Para verificar que HyQuery está funcionando correctamente, puedes probar localmente o de forma remota utilizando diversas herramientas.

 

### Usando el Script de Prueba en Python

 

Descarga y ejecuta el script de prueba incluido en el repositorio:

 

“`bash

# Descargar script de prueba

wget https://raw.githubusercontent.com/hyvote/hyquery/main/test_hyquery.py

 

# Probar tu servidor

python3 test_hyquery.py tu-ip-del-servidor 5520

 

# Probar localmente

python3 test_hyquery.py localhost 5520

“`

 

Una respuesta exitosa mostrará la información de tu servidor:

 

“`

==================================================

Respuesta de HyQuery

==================================================

  Tipo de Respuesta: básico

  Nombre del Servidor:   Mi Servidor de Hytale

  MOTD:          §a¡Bienvenido a §lMi Servidor§r!

  Jugadores:       0/100

  Puerto:          5520

  Versión:       2026.01.13-dcad8778f

==================================================

“`

 

### Usando Herramientas en Línea

 

Muchas listas de servidores proporcionan herramientas de verificación de estado que soportan HyQuery. Por ejemplo:

– [Verificador de Estado de Servidor Hyvote](https://hyvote.org/tools/server-status)

 

## Compatibilidad con Listas de Servidores

 

HyQuery está diseñado para funcionar con listas de servidores de Hytale y servicios de monitorización. Actualmente es compatible con:

 

– **Hyvote** – Soporte completo con HyQuery como método de consulta principal

– **Otras Listas de Servidores** – Muchas listas de servidores están adoptando el soporte de HyQuery

 

Si administras una lista de servidores y deseas añadir soporte para HyQuery, consulta la [documentación de la API](https://github.com/hyvote/hytale-server-api) y la [especificación del protocolo](https://github.com/hyvote/hyquery).

 

## Detalles del Protocolo

 

### Tipos de Consulta

 

HyQuery soporta dos tipos de consulta:

 

1. **Consulta Básica (0x00)** – Devuelve información esencial del servidor:

   – Nombre del servidor

   – MOTD

   – Número de jugadores (en línea/máx)

   – Versión del servidor

   – Puerto del servidor

 

2. **Consulta Completa (0x01)** – Devuelve todo lo de la consulta básica más:

   – Lista de jugadores con UUIDs (si `showPlayerList` está habilitado)

   – Lista de plugins (si `showPlugins` está habilitado)

 

### Formato de Respuesta

 

Todas las respuestas incluyen:

– Bytes mágicos: `HYREPLY`

– Indicador de tipo de consulta

– Cadenas UTF-8 con longitud prefijada

– Enteros de 32 bits en orden little-endian para conteos

– UUIDs de 16 bytes para jugadores

 

## Solución de Problemas

 

### Plugin No Cargando

 

**Verifica los registros de la consola:**

“`

[INFO] HyQuery cargando…

[INFO] HyQuery habilitado en el puerto UDP 5520

“`

 

Si no ves estos mensajes:

– Verifica que el archivo JAR esté en la carpeta `/mods`

– Asegúrate de que descargaste la versión correcta del plugin para tu servidor

– Asegúrate de que no aparezcan errores en la consola durante la inicialización del plugin

 

### Sin Respuesta a las Consultas

Si las consultas están agotando el tiempo:

1. **Verifica que el plugin esté habilitado:**

   – Verifica `enabled: true` en tu config.json

   – Reinicia el servidor después de cualquier cambio en la configuración

2. **Verifica la configuración del cortafuegos:**

   – Asegúrate de que el tráfico UDP esté permitido en el puerto de tu servidor de juego

   – Si tu servidor de juego funciona, HyQuery también debería funcionar (mismo puerto)

3. **Prueba localmente primero:**

   – Usa `localhost` o `127.0.0.1` para verificar que el plugin responda

   – Si local funciona pero remoto no, es un problema de red/cortafuegos

4. **Verifica el puerto:**

   – HyQuery utiliza el puerto de tu servidor de juego (predeterminado 5520)

   – Asegúrate de que estás consultando el puerto correcto

 

### MOTD Personalizado No Mostrándose

Si tu MOTD personalizado no aparece:

1. Verifica `useCustomMotd: true` en config.json

2. Verifica si hay errores de sintaxis en tu cadena de MOTD (especialmente caracteres de escape)

3. Reinicia el servidor después de cambiar la configuración

4. Prueba con una herramienta de consulta para ver la respuesta en bruto

 

### Jugadores/Plugins No Mostrándose

Si las listas de jugadores o plugins no aparecen:

1. Verifica que `showPlayerList` o `showPlugins` estén configurados en `true`

2. Verifica que estés utilizando un tipo de consulta “completa” (0x01), no básica (0x00)

3. Reinicia el servidor después de los cambios en la configuración

 

## Rendimiento

HyQuery está diseñado para ser extremadamente ligero:

– Utiliza UDP (sin sobrecarga de conexión)

– Procesamiento mínimo de paquetes

– Solo procesa paquetes con los bytes mágicos correctos

– Todo el tráfico restante pasa al servidor de juego inmediatamente

– Tiempo típico de respuesta de consulta: 5-15ms

 

## Seguridad y Privacidad

HyQuery prioriza la privacidad:

– La información de los jugadores está oculta por defecto

– La información del plugin está oculta por defecto

– No se requiere autenticación (consultas de solo lectura)

– No se pueden ejecutar comandos ni modificar el estado del servidor

– No se pueden acceder a archivos ni a la configuración del servidor

Habilita `showPlayerList` y `showPlugins` solo si te sientes cómodo compartiendo esta información públicamente.

## Soporte y Desarrollo

– **Código Fuente:** [Repositorio de GitHub](https://github.com/hyvote/hyquery)

– **Rastreador de Problemas:** [Reportar Problemas](https://github.com/hyvote/hyquery/issues)

– **Especificación del Protocolo:** Consulta la documentación del repositorio

– **Integración de API:** [hytale-server-api](https://github.com/hyvote/hytale-server-api)

## Requisitos

– Servidor de Hytale (se recomienda 2026.01.13 o posterior)

– Java 17 o superior

– Puerto UDP accesible (el mismo que el de tu servidor de juego)

## Licencia

Este plugin es de código abierto. Consulta el repositorio para obtener detalles sobre la licencia.

## Créditos

Desarrollado para la comunidad de servidores de Hytale. Agradecimientos especiales a los operadores de servidores que proporcionaron comentarios durante el desarrollo.