VOLVER AL BLOG

Cómo Crear tu Propio Servidor de Hytale

2025-01-15
Equipo Hytale.es

Introducción

Este artículo cubre la configuración, instalación y operación de servidores dedicados de Hytale.

Audiencia objetivo: Administradores de servidores y jugadores que alojan servidores dedicados.

Configuración del Servidor

El servidor de Hytale puede ejecutarse en cualquier dispositivo con al menos 4GB de memoria y Java 25. Tanto arquitecturas x64 como arm64 están soportadas.

Recomendamos monitorear el uso de RAM y CPU mientras el servidor está en uso para entender el consumo típico según tu cantidad de jugadores y estilo de juego - el uso de recursos depende en gran medida del comportamiento de los jugadores.

Guía General

Recurso Factor Principal
CPU Alto número de jugadores o entidades (NPCs, mobs)
RAM Gran área del mundo cargada (alta distancia de renderizado, jugadores explorando independientemente)

Nota: Sin herramientas especializadas, puede ser difícil determinar cuánta RAM asignada realmente necesita un proceso Java. Experimenta con diferentes valores para el parámetro -Xmx de Java para establecer límites explícitos. Un síntoma típico de presión de memoria es el aumento del uso de CPU debido a la recolección de basura.

Instalar Java 25

Instala Java 25. Recomendamos Adoptium.

Confirmar la Instalación

Verifica la instalación ejecutando:

java --version

Salida esperada:

openjdk 25.0.1 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode, sharing)

Archivos del Servidor

Dos opciones para obtener los archivos del servidor:

  1. Copiar manualmente desde tu instalación del Launcher
  2. Usar el Hytale Downloader CLI

Copiar Manualmente desde el Launcher

Ideal para: Pruebas rápidas. Incómodo de mantener actualizado.

Encuentra los archivos en la carpeta de instalación de tu launcher:

  • Windows: %appdata%\Hytale\install\release\package\game\latest
  • Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
  • MacOS: ~/Application Support/Hytale/install/release/package/game/latest

Lista el contenido del directorio:

ls

Salida esperada:

    Directory: C:\Users\...\Hytale\install\release\package\game\latest

Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----        12/25/2025   9:25 PM                Client
d-----        12/25/2025   9:25 PM                Server
-a----        12/25/2025   9:04 PM     3298097359 Assets.zip

Copia la carpeta Server y Assets.zip a la carpeta de destino de tu servidor.

Hytale Downloader CLI

Ideal para: Servidores de producción. Fácil de mantener actualizado.

Una herramienta de línea de comandos para descargar archivos del servidor y assets de Hytale con autenticación OAuth2. Consulta el archivo QUICKSTART.md dentro del archivo comprimido.

Descarga: hytale-downloader.zip (Linux y Windows)

Comando Descripción
./hytale-downloader Descargar la última versión
./hytale-downloader -print-version Mostrar versión del juego sin descargar
./hytale-downloader -version Mostrar versión de hytale-downloader
./hytale-downloader -check-update Verificar actualizaciones de hytale-downloader
./hytale-downloader -download-path game.zip Descargar a un archivo específico
./hytale-downloader -patchline pre-release Descargar desde el canal pre-release
./hytale-downloader -skip-update-check Omitir verificación automática de actualizaciones

Ejecutar un Servidor de Hytale

Inicia el servidor con:

java -jar HytaleServer.jar --assets RutaAAssets.zip

Autenticación

Después del primer arranque, autentica tu servidor.

> /auth login device
===================================================================
AUTORIZACIÓN DE DISPOSITIVO
===================================================================
Visita: https://accounts.hytale.com/device
Introduce el código: ABCD-1234
O visita: https://accounts.hytale.com/device?user_code=ABCD-1234
===================================================================
Esperando autorización (expira en 900 segundos)...

[El usuario completa la autorización en el navegador]

> ¡Autenticación exitosa! Modo: OAUTH_DEVICE

Una vez autenticado, tu servidor puede aceptar conexiones de jugadores.

Información Adicional sobre Autenticación

Los servidores de Hytale requieren autenticación para habilitar la comunicación con nuestras APIs de servicio y para contrarrestar abusos.

Nota: Existe un límite de 100 servidores por licencia de juego de Hytale para prevenir abusos tempranos. Si necesitas más capacidad, compra licencias adicionales o solicita una cuenta de Proveedor de Servidores.

Si necesitas autenticar una gran cantidad de servidores o autenticar servidores dinámicamente de forma automática, por favor lee la Guía de Autenticación para Proveedores de Servidores para información detallada.

Ayuda

Revisa todos los argumentos disponibles:

java -jar HytaleServer.jar --help

Salida esperada:

Option                                   Description
------                                   -----------
--accept-early-plugins                   Reconoce que cargar plugins tempranos
                                           no está soportado y puede causar problemas de estabilidad
--allow-op
--assets <Ruta>                          Directorio de assets (por defecto: ..\HytaleAssets)
--auth-mode <authenticated|offline>      Modo de autenticación (por defecto: AUTHENTICATED)
-b, --bind <InetSocketAddress>           Dirección a escuchar (por defecto: 0.0.0.0:5520)
--backup                                 Habilitar copias de seguridad automáticas
--backup-dir <Ruta>                      Directorio de copias de seguridad
--backup-frequency <Entero>              Intervalo de backup en minutos (por defecto: 30)
[...]

Puerto

El puerto por defecto es 5520. Cámbialo con el argumento --bind:

java -jar HytaleServer.jar --assets RutaAAssets.zip --bind 0.0.0.0:25565

Firewall y Configuración de Red

Hytale usa el protocolo QUIC sobre UDP (no TCP). Configura tu firewall y reenvío de puertos correspondientemente.

Reenvío de Puertos

Si alojas detrás de un router, reenvía el puerto UDP 5520 (o tu puerto personalizado) a tu máquina servidor. No se requiere reenvío TCP.

Reglas de Firewall

Windows Defender Firewall:

New-NetFirewallRule -DisplayName "Servidor Hytale" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow

Linux (iptables):

sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT

Linux (ufw):

sudo ufw allow 5520/udp

Consideraciones de NAT

QUIC maneja bien el NAT traversal en la mayoría de casos. Si los jugadores tienen problemas para conectarse:

  • Asegúrate de que el reenvío de puertos sea específicamente para UDP, no TCP
  • Las configuraciones de NAT simétrico pueden causar problemas - considera un VPS o servidor dedicado
  • Los jugadores detrás de NAT de grado carrier (común en redes móviles) deberían conectarse bien como clientes

Estructura de Archivos

Ruta Descripción
.cache/ Caché para archivos optimizados
logs/ Archivos de log del servidor
mods/ Mods instalados
universe/ Datos de guardado del mundo y jugadores
bans.json Jugadores baneados
config.json Configuración del servidor
permissions.json Configuración de permisos
whitelist.json Jugadores en lista blanca

Estructura del Universo

El directorio universe/worlds/ contiene todos los mundos jugables. Cada mundo tiene su propio config.json:

{
  "Version": 4,
  "UUID": {
    "$binary": "j2x/idwTQpen24CDfH1+OQ==",
    "$type": "04"
  },
  "Seed": 1767292261384,
  "WorldGen": {
    "Type": "Hytale",
    "Name": "Default"
  },
  "WorldMap": {
    "Type": "WorldGen"
  },
  "ChunkStorage": {
    "Type": "Hytale"
  },
  "ChunkConfig": {},
  "IsTicking": true,
  "IsBlockTicking": true,
  "IsPvpEnabled": false,
  "IsFallDamageEnabled": true,
  "IsGameTimePaused": false,
  "GameTime": "0001-01-01T08:26:59.761606129Z",
  "RequiredPlugins": {},
  "IsSpawningNPC": true,
  "IsSpawnMarkersEnabled": true,
  "IsAllNPCFrozen": false,
  "GameplayConfig": "Default",
  "IsCompassUpdating": true,
  "IsSavingPlayers": true,
  "IsSavingChunks": true,
  "IsUnloadingChunks": true,
  "IsObjectiveMarkersEnabled": true,
  "DeleteOnUniverseStart": false,
  "DeleteOnRemove": false,
  "ResourceStorage": {
    "Type": "Hytale"
  },
  "Plugin": {}
}

Cada mundo se ejecuta en su propio hilo principal y descarga trabajo paralelo en un pool de hilos compartido.

Consejos y Trucos

Instalar Mods

Descarga mods (.zip o .jar) de fuentes como CurseForge y colócalos en la carpeta mods/.

Deshabilitar Informes de Errores de Sentry

Importante: Deshabilita Sentry durante el desarrollo activo de plugins.

Usamos Sentry para rastrear errores. Deshabilítalo con --disable-sentry para evitar enviar tus errores de desarrollo:

java -jar HytaleServer.jar --assets RutaAAssets.zip --disable-sentry

Aprovechar la Caché Ahead-of-Time

El servidor viene con una caché AOT pre-entrenada (HytaleServer.aot) que mejora los tiempos de arranque al omitir el calentamiento JIT. Consulta JEP-514.

java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets RutaAAssets.zip

Plugins Recomendados

Nuestros socios de desarrollo en Nitrado y Apex Hosting mantienen plugins para necesidades comunes de alojamiento de servidores:

Plugin Descripción
Nitrado:WebServer Plugin base para aplicaciones web y APIs
Nitrado:Query Expone el estado del servidor (conteo de jugadores, etc.) vía HTTP
Nitrado:PerformanceSaver Limita dinámicamente la distancia de renderizado basándose en el uso de recursos
ApexHosting:PrometheusExporter Expone métricas detalladas del servidor y JVM

Distancia de Renderizado

La distancia de renderizado es el principal factor para el uso de RAM. Recomendamos limitar la distancia máxima de renderizado a 12 chunks (384 bloques) tanto para rendimiento como para jugabilidad.

Para comparación: Los servidores de Minecraft tienen por defecto 10 chunks (160 bloques). El valor por defecto de Hytale de 384 bloques es aproximadamente equivalente a 24 chunks de Minecraft. Espera mayor uso de RAM con la configuración por defecto - ajusta este valor basándote en tu cantidad esperada de jugadores.

Arquitectura Multiservidor

Hytale soporta mecanismos nativos para enrutar jugadores entre servidores. No se requiere un reverse proxy como BungeeCord.

Referencia de Jugadores

Transfiere un jugador conectado a otro servidor. El servidor envía un paquete de referencia conteniendo el host de destino, puerto y un payload opcional de 4KB. El cliente abre una nueva conexión al destino y presenta el payload durante el handshake.

PlayerRef.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

⚠️ Advertencia de Seguridad: El payload se transmite a través del cliente y puede ser manipulado. Firma los payloads criptográficamente (ej. HMAC con un secreto compartido) para que el servidor receptor pueda verificar la autenticidad.

Casos de uso: Transferir jugadores entre servidores de juego, pasar contexto de sesión, controlar acceso detrás de matchmaking.

Próximamente: Array de destinos intentados en secuencia para conexiones de fallback.

Redirección de Conexión

Durante el handshake de conexión, un servidor puede rechazar al jugador y redirigirlo a un servidor diferente. El cliente se conecta automáticamente a la dirección redirigida.

PlayerSetupConnectEvent.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)

Casos de uso: Balanceo de carga, enrutamiento regional de servidores, forzar conexiones primero al lobby.

Fallback de Desconexión

Cuando un jugador es desconectado inesperadamente (caída del servidor, interrupción de red), el cliente se reconecta automáticamente a un servidor de fallback preconfigurado en lugar de volver al menú principal.

Casos de uso: Devolver jugadores a un lobby después de una caída del servidor de juego, mantener el engagement durante reinicios.

Próximamente: Implementación de paquete de fallback esperada dentro de semanas después del lanzamiento de Early Access.

Construir un Proxy

Construye servidores proxy personalizados usando Netty QUIC. Hytale usa QUIC exclusivamente para comunicación cliente-servidor.

Las definiciones de paquetes y la estructura del protocolo están disponibles en HytaleServer.jar:

com.hypixel.hytale.protocol.packets

Usa estas para decodificar, inspeccionar, modificar o reenviar tráfico entre clientes y servidores backend.

Detalles Varios

Argumentos de Línea de Comandos de Java

Consulta la Guía de los Parámetros JVM Más Importantes para temas como -Xms y -Xmx para controlar el tamaño del heap.

Actualizaciones de Protocolo

El protocolo de Hytale usa un hash para verificar la compatibilidad cliente-servidor. Si los hashes no coinciden exactamente, la conexión es rechazada.

Limitación Actual: Cliente y servidor deben estar en la misma versión exacta del protocolo. Cuando lanzamos una actualización, los servidores deben actualizarse inmediatamente o los jugadores en la nueva versión no pueden conectarse.

Próximamente: Tolerancia de protocolo permitiendo diferencia de ±2 versiones entre cliente y servidor. Los operadores de servidores tendrán una ventana para actualizar sin perder conectividad de jugadores.

Archivos de Configuración

Los archivos de configuración (config.json, permissions.json, etc.) se leen al iniciar el servidor y se escriben cuando ocurren acciones en el juego (ej. asignar permisos vía comandos). Los cambios manuales mientras el servidor está corriendo probablemente serán sobrescritos.

Artefacto de Maven Central

El jar de HytaleServer será publicado en Maven Central para usarse como dependencia en proyectos de modding.

<dependency>
    <groupId>com.hypixel.hytale</groupId>
    <artifactId>Server</artifactId>
</dependency>

Los detalles exactos incluyendo versionado están pendientes para el lanzamiento. Consulta los recursos de la comunidad de modding para la información más reciente sobre el uso de estas dependencias.

Adiciones Futuras

Descubrimiento de Servidores y Minijuegos

Un catálogo de descubrimiento accesible desde el menú principal donde los jugadores pueden buscar y encontrar servidores y minijuegos. Los operadores de servidores pueden optar por aparecer en el catálogo para promocionar su contenido directamente a los jugadores.

Requisitos para el Listado

Requisito Descripción
Directrices para Operadores de Servidores Los servidores deben adherirse a las directrices de operadores y estándares de la comunidad
Auto-Clasificación Los operadores deben clasificar con precisión el contenido de su servidor. Las clasificaciones potencian el filtrado de contenido y controles parentales
Aplicación Los servidores que violen su auto-clasificación están sujetos a acciones de aplicación según las políticas de operadores de servidores

Verificación del Conteo de Jugadores

Los conteos de jugadores mostrados en el descubrimiento de servidores se recopilan de la telemetría de clientes en lugar de datos reportados por el servidor. Esto previene la falsificación de conteos y asegura que los jugadores puedan confiar en los números que ven al buscar servidores. Los servidores aún podrán reportar un conteo de jugadores no verificado a usuarios que agregaron el servidor fuera del descubrimiento de servidores.

Grupos (Parties)

Un sistema de grupos que permite a los jugadores agruparse y permanecer juntos a través de transferencias de servidor y colas de minijuegos.

Integración con el descubrimiento de servidores:

Los jugadores pueden buscar servidores con su grupo y unirse juntos. Los requisitos de tamaño de grupo y restricciones son visibles antes de unirse, para que los grupos sepan de antemano si pueden jugar juntos.

Este sistema proporciona la base para una experiencia social fluida donde los amigos pueden moverse a través del ecosistema de Hytale como grupo sin coordinación manual.

Sistema de Pagos Integrado

Una pasarela de pago integrada en el cliente que los servidores pueden usar para aceptar pagos de jugadores. Opcional pero recomendado.

Beneficios para operadores de servidores:

  • Acepta pagos sin manejar detalles de pago o construir infraestructura
  • Transacciones procesadas a través de un sistema seguro y confiable

Beneficios para jugadores:

  • No necesitas visitar sitios web externos
  • Todas las transacciones son seguras y rastreables
  • La información de pago permanece dentro del ecosistema de Hytale

Soporte de Registros SRV

Los registros SRV permiten a los jugadores conectarse usando un nombre de dominio (ej. play.ejemplo.com) sin especificar un puerto, con DNS manejando la búsqueda para resolver la dirección real del servidor y puerto.

Estado Actual: No soportado. En evaluación.

Por qué no está disponible aún:

No existe una librería C# probada en batalla para resolución de registros SRV. Las opciones existentes requieren incorporar una implementación completa de cliente DNS, lo que introduce complejidad innecesaria y potenciales riesgos de estabilidad, o carecen de la preparación para producción que requerimos para una característica central de networking.

Estamos evaluando alternativas y revisaremos esto cuando exista una solución adecuada.

Endpoints de API de Primera Parte

Los servidores autenticados tendrán acceso a endpoints oficiales de API para datos de jugadores, versionado y operaciones de servidor. Estos endpoints reducen la necesidad de servicios de terceros y proporcionan datos autoritativos directamente desde Hytale.

Endpoints Planificados

Endpoint Descripción
Búsqueda UUID ↔ Nombre Resolver nombres de jugadores a UUIDs y viceversa. Soporta búsquedas individuales y masivas
Versión del Juego Consultar versión actual del juego, versión del protocolo y verificar actualizaciones
Perfil de Jugador Obtener datos del perfil del jugador incluyendo cosméticos, renders de avatar e información de perfil pública
Telemetría del Servidor Reportar estado del servidor, conteo de jugadores y metadatos para integración con el descubrimiento
Reportar Reportar jugadores por violaciones de ToS
Pagos Procesar pagos usando nuestra pasarela de pago integrada

Bajo Consideración

Endpoint Descripción
Sanciones Globales Consultar si un jugador tiene sanciones a nivel de plataforma (no baneos específicos del servidor)
Lista de Amigos Obtener la lista de amigos de un jugador (con permisos apropiados) para características sociales
Suscripciones a Webhooks Suscribirse a notificaciones push para eventos como cambios de nombre de jugador o actualizaciones de sanciones

Objetivos de Diseño

  • Límites de tasa generosos: Endpoints masivos y respuestas compatibles con caché para soportar grandes redes
  • Acceso autenticado: Todos los endpoints requieren autenticación del servidor para prevenir abuso
  • API versionada: Contratos estables con ventanas de deprecación para cambios disruptivos