Hytale Multiserver Architecture: Player Referral, Redirects, and Network Setup

Hytale supports native mechanisms for routing players between servers without requiring a reverse proxy like BungeeCord. This guide covers how to build multiserver networks with player referrals, redirects, and fallbacks.

No Proxy Required

Unlike Minecraft which often requires BungeeCord or Velocity, Hytale has built-in multiserver support. You can transfer players between servers directly using the game’s native APIs.

Player Referral System

Player referral transfers a connected player to another server. The source server sends a referral packet containing the target host, port, and an optional payload.

How It Works

1. Server calls PlayerRef.referToServer()
2. Client receives target host, port, and optional 4KB payload
3. Client opens new connection to target server
4. Payload is presented during handshake

API Example

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

Use Cases

• Transferring players between game servers
• Passing session context between servers
• Gating access behind matchmaking
• Building lobby systems

Connection Redirect

During connection handshake, a server can reject the player and redirect them to a different server. The client automatically connects to the redirected address.

API Example

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

Use Cases

• Load balancing: Distribute players across multiple servers
• Regional routing: Send players to geographically closer servers
• Enforcing lobby-first: Require players to connect through a lobby

Disconnect Fallback

When a player is unexpectedly disconnected (server crash, network interruption), the client can automatically reconnect to a pre-configured fallback server instead of returning to the main menu.

Use Cases

• Returning players to lobby after game server crash
• Maintaining engagement during server restarts
• Graceful handling of maintenance windows

Building a Custom Proxy

For advanced use cases, you can build custom proxy servers using Netty QUIC. Hytale uses QUIC exclusively for client-server communication.

Packet Access

Packet definitions and protocol structure are available in HytaleServer.jar:

com.hypixel.hytale.protocol.packets

Use these to decode, inspect, modify, or forward traffic between clients and backend servers.

Network Architecture Examples

Simple Lobby + Game Servers

┌─────────┐     ┌─────────────┐
│  Lobby  │────▶│ Game Server │
│  Server │     │     #1      │
└─────────┘     └─────────────┘
     │          ┌─────────────┐
     └─────────▶│ Game Server │
                │     #2      │
                └─────────────┘

Hub with Regional Routing

┌──────────────┐
│   Main Hub   │
└──────────────┘
       │
   ┌───┴───┐
   ▼       ▼
┌─────┐ ┌─────┐
│ US  │ │ EU  │
│ Hub │ │ Hub │
└─────┘ └─────┘

Best Practices

Security

• Always sign payloads with HMAC or similar
• Validate all incoming referral data
• Use internal network for server-to-server communication

Reliability

• Implement fallback servers for all game servers
• Monitor server health for redirect decisions
• Handle connection failures gracefully