MLoadBalancer – Secure transfer and load balancing / BungeeCord alternative

Un sistema de balanceo de carga para servidores de Hytale con autenticación JWT. Soporta dos modos de operación: lobby (redirige jugadores) y target (recibe jugadores redirigidos).

MLoadBalancer es una alternativa nativa a BungeeCord (proxies de Minecraft) desarrollada específicamente para Hytale.

¿Por qué usar MLoadBalancer en lugar de BungeeCord?

Nativo para Hytale: Construido específicamente para la API de Hytale, no se necesita un proxy externo
Autenticación Integrada: JWT con firma HMAC, seguridad incorporada en el juego mismo
Más Simple: No es necesario ejecutar un servidor proxy separado – funciona como un plugin dentro del servidor
Mejor Rendimiento: Redirección nativa de Hytale, sin intermediarios
Fácil Configuración: Todo en un solo archivo JSON5, sin configuraciones de red complejas

Comparación rápida:

BungeeCord: Proxy externo que se sitúa entre el cliente y los servidores (arquitectura de proxy)
MLoadBalancer: Plugin nativo que redirige a los jugadores directamente (arquitectura de balanceador de carga)

Si vienes de Minecraft y conoces BungeeCord, ¡MLoadBalancer cumple la misma función, pero de una manera más integrada y nativa para Hytale!

¿Qué es esto?

MLoadBalancer te permite tener un servidor de lobby que distribuye automáticamente a los jugadores a múltiples servidores de juego. Es como una “puerta de entrada” que dirige a los jugadores a diferentes salas de juego.

¿Cómo funciona?

El jugador se conecta al servidor lobby
El lobby crea un token seguro (JWT) para el jugador
El lobby redirige al jugador a uno de los servidores target
El servidor target valida el token y permite que el jugador se una
Las conexiones directas a los targets están bloqueadas (seguridad)

Características

Modo Doble: Funciona como lobby (redirige) o target (recibe)
Autenticación Segura: Tokens JWT con firma HMAC (no pueden ser falsificados)
Balanceo de Carga: Distribuye jugadores a través de múltiples servidores
Configuración Simple: Archivo JSON5 fácil de editar
Seguridad: Bloquea conexiones directas a servidores target (solo el lobby puede redirigir)
API de Plugin: Plugins externos pueden enviar datos personalizados a través de tokens JWT
Eventos:
- LoadBalancerBeforeRedirectEvent – se activa antes de la redirección del jugador (lobby)
- PlayerLobbyConnectionEvent – se activa cuando los jugadores se conectan desde el lobby (target)

Cómo Usar (Guía Paso a Paso)

Paso 1: Entender los Modos

Necesitas dos tipos de servidores:

Servidor de Lobby (modo “lobby”)

Este es el servidor al que los jugadores se conectan primero
Nunca permite que los jugadores permanezcan conectados a él
Siempre redirige a los jugadores a un servidor target
Necesita una lista de servidores target configurada

Servidor Target (modo “target”)

Estos son los servidores donde ocurre el juego real
Reciben jugadores redirigidos desde el lobby
Bloquean conexiones directas (solo aceptan a través del lobby)
Necesitan tener el mismo secreto JWT que el lobby

Paso 2: Configurar el Secreto JWT (¡CRÍTICO!)

⚠️ ADVERTENCIA: Este es el paso más importante!

El jwt.secret es como una “contraseña maestra” que TODOS los servidores deben compartir. Se utiliza para crear y validar tokens de autenticación.

Reglas del Secreto:

Debe tener al menos 32 caracteres (cuanto más largo, más seguro)
Debe ser exactamente el mismo en TODOS los servidores (lobby Y targets)
Usar una mezcla de letras, números y símbolos
¡NUNCA compartirlo públicamente
Si los secretos no coinciden, los jugadores serán rechazados

Cómo crear un buen secreto:

❌ Malo: "secret123"
✅ Bueno: "MySuperSecretKey2024!ThatNobodyCanGuess12345@#$%"
✅ Excelente: Usa un generador de contraseñas aleatorias con 40+ caracteres

Ejemplo práctico:

Servidor de lobby: "jwt.secret": "MySuperSecurePassword2024!DontShare123"
Servidor target 1: "jwt.secret": "MySuperSecurePassword2024!DontShare123" ✅
Servidor target 2: "jwt.secret": "MySuperSecurePassword2024!DontShare123" ✅

¡Si algún servidor tiene un secreto diferente, los tokens no funcionarán!

Paso 3: Configurar el Servidor de Lobby

Edita el archivo: config/com.machina/mloadbalancer/config.json5

Nota: Los mensajes para los jugadores se configuran en un archivo separado: config/com.machina/mloadbalancer/translation.json5. Consulta la sección “Mensajes Configurables” a continuación para más detalles.

{
  // Habilitar o deshabilitar el balanceador de carga globalmente
  // Cuando es falso, el plugin no hace nada (útil para mantenimiento o pruebas)
  "enabled": true,

  // Cómo funciona este servidor: "lobby" significa que redirige a los jugadores
  "mode": "lobby",

  // CONTRASEÑA COMPARTIDA - ¡Debe ser la MISMA en TODOS los servidores!
  "jwt": {
    "secret": "YOUR-SUPER-SECURE-PASSWORD-HERE-MINIMUM-32-CHARACTERS",
    "expirationMinutes": 5
  },

  // Configuración del lobby
  "lobby": {
    // Cuando es verdadero, los jugadores NUNCA pueden permanecer en el lobby - siempre redirigidos o desconectados
    "preventDirectConnections": true
  },

  // Cómo elegir qué servidor recibe al jugador
  // "round-robin" = distribuye de manera uniforme (recomendado)
  // "random" = elige aleatoriamente
  "strategy": "round-robin",

  // Lista de servidores target a los que redirigir a los jugadores
  "servers": [
    {
      "name": "Game Server 1",           // Nombre amigable (solo para registros)
      "host": "192.168.1.100",           // IP o dominio del servidor target
      "port": 5520,                      // Puerto del servidor (el puerto predeterminado de Hytale es 5520)
      "enabled": true                    // true = usar este servidor, false = desactivar temporalmente
    },
    {
      "name": "Game Server 2",
      "host": "192.168.1.101",
      "port": 5520,
      "enabled": true
    },
    {
      "name": "Game Server 3",
      "host": "game.example.com",        // Puedes usar IP o dominio
      "port": 5520,
      "enabled": false                   // Desactivado - este servidor no recibirá jugadores
    }
  ]
}

Paso 4: Configurar cada Servidor Target

Edita el archivo: config/com.machina/mloadbalancer/config.json5 en CADA servidor target

{
  // Habilitar o deshabilitar el balanceador de carga globalmente
  // Cuando es falso, el plugin no hace nada (útil para mantenimiento o pruebas)
  "enabled": true,

  // Cómo funciona este servidor: "target" significa que recibe jugadores redirigidos
  "mode": "target",

  // CONTRASEÑA COMPARTIDA - ¡Debe ser EXACTAMENTE IGUAL que el servidor de lobby!
  "jwt": {
    "secret": "YOUR-SUPER-SECURE-PASSWORD-HERE-MINIMUM-32-CHARACTERS",  // ¡MISMO que el lobby!
    "expirationMinutes": 5
  }
}

Paso 5: Verificar el Puerto

⚠️ Importante: ¡Hytale utiliza el puerto predeterminado 5520, no 25565 como Minecraft!

Asegúrate de:

Que tus servidores target estén funcionando en el puerto 5520 (o el puerto que configuraste)
Que el puerto en el archivo de configuración del lobby coincida con el puerto real de los targets

Opciones de Configuración

Habilitar/Deshabilitar el Balanceador de Carga

Puedes deshabilitar globalmente el balanceador de carga sin eliminar el plugin configurando "enabled": false en la configuración:

{
  "enabled": false,  // Desactiva completamente el balanceador de carga
  "mode": "lobby",
  // ... resto de la configuración
}

Cuando está deshabilitado:

No se registran controladores de eventos
El plugin no hace nada (los jugadores pueden conectarse normalmente)
Útil para mantenimiento, pruebas o desactivar temporalmente el balanceo de carga
La configuración aún se carga, pero no hay funcionalidad activa

Predeterminado: true (habilitado)

Explicaciones Detalladas

¿Qué es JWT y por qué lo necesito?

JWT (JSON Web Token) es un “ticket de autenticación” seguro que prueba que un jugador vino del servidor de lobby.

Problema que resuelve:

Los jugadores podrían conectarse directamente a los servidores target, saltándose el lobby
Sin JWT, no hay forma de probar que un jugador vino del lobby

¿Cómo funciona?

El lobby crea un token con el UUID del jugador + expiración
El token está firmado con el secreto (HMAC) – esto previene la falsificación
El token se envía junto con la redirección
El target valida la firma usando el mismo secreto
Si la firma es válida = el jugador vino del lobby ✅
Si la firma es inválida = conexión bloqueada ❌

¿Por qué el secreto necesita ser el mismo? Es como una llave y una cerradura: la llave (secreto) que crea el token necesita ser la misma que valida. Si son diferentes, la validación falla.

¿Cómo funciona el Balanceo de Carga?

Round-Robin (Recomendado):

Jugador 1 → Servidor 1
Jugador 2 → Servidor 2
Jugador 3 → Servidor 3
Jugador 4 → Servidor 1 (de vuelta al primero)
Resultado: Distribución equitativa entre todos los servidores

Aleatorio:

Elige cualquier servidor aleatorio de la lista
No garantiza distribución equitativa
Más simple, pero menos balanceado

¿Qué es “preventDirectConnections”?

Cuando está habilitado (true):

Asegura que NINGÚN jugador permanezca conectado al lobby
Los jugadores son siempre redirigidos o desconectados
El lobby funciona como un “enrutador puro” – solo redirige

Cuando está deshabilitado (false):

Los jugadores podrían teóricamente permanecer en el lobby (pero aún serán redirigidos en PlayerReadyEvent)
No se recomienda para un balanceador de carga real

Recomendación: Mantenerlo siempre true para asegurar un comportamiento consistente.

¿Por qué son seguros los Tokens JWT?

Firma HMAC: El token está firmado con una clave secreta (HMAC-SHA)
No puede ser falsificado: Sin el secreto, es imposible crear un token válido
Validación en el Target: El target verifica la firma antes de aceptar al jugador
Expiración: Los tokens expiran después de unos minutos (configurable)

¿Qué sucede si alguien intenta falsificar?

❌ Intento: El jugador modifica el token en el cliente
✅ Resultado: La firma no coincide → Conexión rechazada

❌ Intento: El jugador se conecta directamente al target (sin token)
✅ Resultado: isReferralConnection() == false → Conexión rechazada

❌ Intento: El jugador usa un token expirado
✅ Resultado: La validación falla → Conexión rechazada

Mejores Prácticas de Seguridad

Usar secretos fuertes…