Connection Redirect Rules

warning

Direct IP connections are not blocked by default Players can reach your server directly via IP address and port. All routing rules are still evaluated, but only those that apply to the server they connected to directly.

If you want to restrict or block direct IP connections, you must explicitly configure a routing rule for this. The HMAC Payload condition is ideal for this: direct connections from outside the network never carry a valid HMAC token, so you can reliably detect and reject or redirect them.

Connection redirect rules let you control what happens the moment a player tries to connect to your network. Before the player fully joins, OrbisManager checks your rules from top to bottom and applies the first one that matches.

You can use this to:

• Send players from a specific region to their closest server
• Block connections when a server is under maintenance
• Redirect players with a certain permission to a VIP server
• Show a message to players who connect at the wrong time

Network Topology

No proxy involved

OrbisManager does not act as a proxy. All connections are direct Hytale connections. When a player is redirected, the Hytale client receives a native ClientReferral and connects directly to the target server.

Direct Server Connection

OrbisManager runs as a mod on each Hytale Game Server. Players can connect via IP or hostname (SNI/Hostname is passed natively by the Hytale client). When a player connects, OrbisManager evaluates the routing rules and decides what happens.

When a redirect rule fires, the player receives a ClientReferral and their client connects directly to the target server.

With OrbisRouter

OrbisRouter is a dedicated routing gateway. Players connect via hostname (e.g. play.example.com) and OrbisRouter evaluates routing rules to determine which Hytale Game Server they are sent to via a native ClientReferral.

How rules work

Each rule has two parts:

1. Conditions: When should this rule trigger? (All conditions must match)
2. Action: What happens when it triggers?

Rules are checked in order by priority. The first matching rule wins. You can reorder rules using the up/down arrows.

Conditions

You can combine multiple conditions in one rule. All of them must be true for the rule to fire.

Direct Connect

Checks the hostname a player used to connect.

Examples:

• Player connected via play.example.com → redirect to EU server
• Player used eu.example.com → send to EU pool

Player Latency

Checks the player's latency (ping) at the moment they connect. This is a one-time check during the connection handshake. It does not monitor latency while the player is already on the server.

note

This condition is only evaluated when the player connects directly to a Hytale Game Server. It is not available when rules are evaluated by an OrbisRouter.

Examples:

• Ping over 200ms → redirect to a closer server
• Ping under 50ms → allow through to main server

SNI / Hostname

Similar to Direct Connect, but checks the full domain name (hostname) the player used, including subdomains. This works via DNS: when a player types eu.play.example.com into their client, that domain name is passed along with the connection. OrbisManager reads it and can route the player based on it.

Use this when you have multiple domains or subdomains pointing to the same server and want to route players differently depending on which one they used.

Examples:

• Player connected via eu.play.example.com → send to EU server
• Player connected via us.play.example.com → send to US server

Server Full

Triggers when a specific server or pool has reached its max player count.

Example:

• Lobby-1 is full → send player to Lobby-2

Player Region (GeoIP)

Checks where the player is connecting from using their IP location.

Countries are specified as a two-letter country code (ISO 3166-1 alpha-2), for example DE for Germany, US for the United States, FR for France, or GB for the United Kingdom. The code is case-insensitive.

You can enter a single country code or multiple codes separated by commas (e.g. DE,AT,CH). Spaces around the commas are ignored. You can match players from those countries or players not from those countries (negation).

If a player's IP address cannot be located, the condition is treated as not matching, so the rule is skipped.

Examples:

• Player is from DE → send to EU server
• Player is not from US → show a region restriction message
• Player is from AT or CH → redirect to German-speaking server

Time Window

Only applies during a specific time range.

Examples:

• Between 00:00–06:00 UTC → redirect to maintenance server
• Outside 10:00–22:00 Europe/Berlin → show "Server closed" message

HMAC Payload

Checks whether the player's connection includes a valid cryptographic token.

Behavior by connection type:

Situation	HMAC Payload
Player connects fresh from outside (direct IP or domain, new session)	Missing / invalid
Player is already on the network and gets redirected from server to server	Always present and valid

This means: by checking for a missing or invalid HMAC payload, you can reliably identify direct external connections and block or redirect them accordingly.

Server Tag

Checks whether a specific server (or any server in a pool) currently has a certain tag.

Examples:

• Server has tag maintenance → redirect players away
• No server in pool has tag open → block connections

Player Tag

Checks whether the connecting player has been assigned a tag on their previous server.

Examples:

• Player has tag vip → send to VIP server
• Player has tag banned → disconnect them

Player Permission

Checks whether the player has a specific permission node.

Examples:

• Has network.staff → send to staff server
• Does not have network.premium → show upgrade message

Actions

Redirect

Sends the player to a different server or pool.

Disconnect

Disconnects the player. You can optionally include a message explaining why.

tip

Disconnect messages support TinyMessage tags for colors and formatting. See the TinyMessage guide for available tags.

<color:red>This server is currently under maintenance.</color>

Show Message

Displays a message to the player without disconnecting them. The connection continues normally after the message.

tip

Show Message also supports TinyMessage tags. See the TinyMessage guide for available tags.

Example rules

Maintenance mode:

• Condition: Server tag maintenance is set on Main Server
• Action: Redirect → Lobby Pool

Region routing:

• Condition: Player region is DE or EU
• Action: Redirect → EU Game Servers pool

Full server:

• Condition: Server Full → Lobby-1
• Action: Redirect → Lobby-2

Time restriction:

• Condition: Time window 00:00–08:00 UTC
• Action: Disconnect with message "Server is closed for maintenance. Come back later!"