Multiserver Architecture

Hytale has native support for routing players between servers. No reverse proxy like BungeeCord is required.

Overview

Built-in mechanisms for server networks:

Feature	Description	Status
Player Referral	Transfer connected players	Available
Connection Redirect	Redirect during handshake	Available
Disconnect Fallback	Auto-reconnect to fallback server	Coming Soon

Player Referral

Transfers a connected player to another server.

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

How it works:

1. Server sends referral packet with target host, port, and optional payload (up to 4KB)
2. Client opens new connection to target
3. Client presents payload during handshake

Use cases:

• Transferring between game servers
• Passing session context
• Gating access behind matchmaking

Security Warning

The payload is transmitted through the client and can be tampered with.

Sign payloads cryptographically (e.g., HMAC with a shared secret) so the receiving server can verify authenticity.

Coming soon: Array of targets tried in sequence for fallback connections.

Connection Redirect

Redirect players during the connection handshake before they fully join.

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

Use cases:

• Load balancing
• Regional server routing
• Enforcing lobby-first connections

The client automatically connects to the redirected address.

Disconnect Fallback

When a player unexpectedly disconnects (server crash, network interruption), they 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

Coming Soon

Fallback packet implementation is expected within weeks after Early Access launch.

Building Custom Proxies

For advanced network setups, build custom proxy servers using:

• Netty QUIC
• Packet definitions from com.hypixel.hytale.protocol.packets

This allows you to:

• Decode and inspect traffic
• Modify packets
• Forward between clients and backend servers

Architecture Patterns

Simple Network

[Players] → [Lobby Server] → [Game Servers]

Use player referral to move between servers.

Load Balanced

[Players] → [Entry Server] → [Game Servers (pool)]
                ↓
        (Connection Redirect)

Entry server redirects to least-loaded game server.

Resilient Network

[Players] → [Game Server]
                ↓ (crash)
           [Fallback Lobby]

Players return to lobby automatically on crash.