MLoadBalancer

A load balancer system for Hytale servers with JWT authentication. Supports two operation modes: lobby (redirects players) and target (receives redirected players).

BungeeCord Alternative for Hytale

MLoadBalancer is a native alternative to BungeeCord (Minecraft proxies) specifically developed for Hytale.

Why use MLoadBalancer instead of BungeeCord?

• Native to Hytale: Built specifically for Hytale's API, no external proxy needed
• Integrated Authentication: JWT with HMAC signature, security built into the game itself
• Simpler: No need to run a separate proxy server - works as a plugin inside the server
• Better Performance: Native Hytale redirection, no intermediary
• Easy Configuration: Everything in a single JSON5 file, no complex network setup

Quick comparison:

• BungeeCord: External proxy that sits between client and servers (proxy architecture)
• MLoadBalancer: Native plugin that redirects players directly (load balancer architecture)

If you're coming from Minecraft and know BungeeCord, MLoadBalancer serves the same purpose, but in a more integrated and native way for Hytale!

What is this?

MLoadBalancer allows you to have one lobby server that automatically distributes players to multiple game servers. It's like an "entry gate" that directs players to different game rooms.

How it works:

1. Player connects to the lobby server
2. Lobby creates a secure token (JWT) for the player
3. Lobby redirects the player to one of the target servers
4. Target server validates the token and allows the player to join
5. Direct connections to targets are blocked (security)

Features

Smooth multi-server player routing 🚀 with no external proxy required. Secure JWT-based handoff between lobby and target servers 🔐. Hot-reloadable configuration 🎛 for zero-downtime changes. Supports both automatic and COMMANDS-based redirection 📡. Optional per-server COMMANDS for faster UX 🔌. Integrates with plugins via API 🧩.

MLoadBalancer is designed for real server environments where players should seamlessly move between instances without noticing the infrastructure behind it. The plugin supports both lobby redirection and target validation with JWT security. Instead of requiring a proxy like BungeeCord, everything happens natively inside Hytale.

Key capabilities include load balancing, secure token handoff, optional command-based routing, per-server shortcuts, permission-aware access (in COMMANDS mode), and a hot-reloadable configuration so operators can make changes without rebooting the network.

Dispatch Modes

Players can be redirected automatically (LOAD_BALANCER) or choose their destination manually (COMMANDS), depending on network design and player flow 🎮. Automatic redirection is ideal when the lobby acts purely as an entry router, while COMMANDS mode is more suitable for hubs where players need choice, tiered access or a persistent social space.

Per-Server Custom Commands

When using COMMANDS mode, servers may optionally define a customCommand block. This enables shortcut COMMANDS such as /survival or /vip, making redirection faster and more intuitive for players who might otherwise need to type /redirect survival 🧭. Custom commands coexist with the global redirect command, and if a global command is not defined, it simply will not be registered.

Permissions

Permission checks apply only in COMMANDS mode and allow role‑based access control such as VIP‑only servers, staff‑only backends or tiered experiences 🔑. When permission is set to null, the server is open to all players. This model mirrors common Minecraft BungeeCord networks while remaining native to Hytale.

Future Enhancements

Future work includes support for permissions in LOAD_BALANCER mode, weighted balancing ⚖️, player counts 📊, health checks 🩺, and expanded UX options 🎨. GUI-based redirection 🖱️ and world portal-based redirection 🌀 are also planned so players can select servers through interactive elements rather than only via COMMANDS. These UX features will build on the existing API and authentication pipeline.

Plugin API Integration

MLoadBalancer exposes an integration API that allows external plugins to participate in server routing or attach custom payload data to the JWT token 📦. This makes it possible to forward matchmaking assignments, player ranks, queue state or other gameplay context from the lobby to the target server without inventing new network protocols.

Target servers can later read the forwarded data and act on it, enabling richer cross‑server flows such as automated matchmaking, queued games or inter‑server minigames 🧩.

Configuration

Configuration for MLoadBalancer lives in:

• config/com.machina/mloadbalancer/config.json5 (preferred when writable)
• fallback: mods/com.machina/mloadbalancer/config.json5 (when the primary path cannot be written)

Configuration files use JSON5, allowing trailing commas and comments.

In addition, localized/translatable player-facing messages live in:

• config/com.machina/mloadbalancer/translation.json5
• fallback: mods/com.machina/mloadbalancer/translation.json5

This makes configuration paths consistent across all Machina plugins. JSON5, allowing trailing commas and comments.

Core Settings

• enabled: master switch for enabling the load balancer
• role: lobby or target, defining the server's behavior
• jwt.secret: shared HMAC secret for token signing/validation
• jwt.expirationMinutes: validity window for referral tokens

Lobby Settings

• dispatchMode: LOAD_BALANCER (automatic) or COMMANDS (player‑selected)
• lobby.preventDirectConnections: avoid players staying in lobby
• loadBalancer.strategy: round-robin or random
• servers[]: list of target servers with host, port, enabled and permission

COMMANDS Mode

• command.name: global redirect command (e.g. redirect)
• servers[].customCommand.name: optional per‑server shorthand command
• servers[].permission: restrict access when in COMMANDS mode

A global command is optional; if absent, it is not registered. Per‑server commands remain available.

Target Settings

• role = target: server accepts only JWT‑authenticated lobby referrals

Support Development

You can support development here 💖 to help fuel future updates and features:

https://machinastudios.net/support-us

Community

You can support development here 💖 to help fuel future updates and features:

https://machinastudios.net/support-us

Community

💬 Join our Discord community!

Get help, share ideas, and connect with other developers 🧑‍💻:

• 🆘 Support and troubleshooting
• 💡 Suggestions and feedback
• 🤝 Community and collaboration

👉 Join our Discord Server: https://discord.gg/QAFrzj48EN