HyTari Studios · Official configuration guide

Server Router

Configure the network by understanding every module.

A practical reference for Server Router - Network Sync. Follow the modules from server identity and routes to shared systems, the native scoreboard and optional inventory synchronization. Each section pairs copyable JSON with an explanation of what the settings actually do.

START THE GUIDE MOD PAGE

BEFORE YOU START

Getting started

STEP 01

Install on every server

Use the same ServerRouter build on every node that participates in the network.

STEP 02

Configure one node at a time

Give every server a unique serverId, its own host/port and the correct role.

STEP 03

Test before opening access

Verify routes and backend protection with staff accounts before relying on them for public traffic.

ServerRouter is network infrastructure: configure credentials, host names, permissions and direct-access rules deliberately. Keep a backup of production configuration before changing multiple modules at once.

CHAPTER 01 · 1 EXAMPLES

Installation and role

Identify the server in the network and decide whether it acts as router, backend, or both.

01CONFIGURATION

Server identity and role

Every network node needs a unique serverId and an address reachable by the other servers.

CONFIGURATION

{
  "enabled": true,
  "role": "both",
  "serverId": "hub",
  "host": "hub.example.com",
  "port": 5520,
  "maxPlayers": 100,
  "acceptingPlayers": true
}

mods/ServerRouter/config.json

WHAT IT DOES

Every network node needs a unique serverId and an address reachable by the other servers.

IMPORTANT BEHAVIOR

role: main enables routing functions, backend accepts transfers, and both combines the two roles.
serverId must remain stable and match the value used in routes and network modules.
acceptingPlayers can temporarily remove a server from available destinations without shutting it down.

CHAPTER 02 · 1 EXAMPLES

Database and heartbeat

Configure MariaDB and how often each server publishes its status.

01CONFIGURATION

MariaDB, heartbeat and online status

ServerRouter uses MariaDB to share status, presence, transfers, and network modules.

CONFIGURATION

{
  "databaseHost": "127.0.0.1",
  "databasePort": 3306,
  "databaseName": "hytale_network",
  "databaseUser": "serverrouter",
  "databasePassword": "CHANGE_ME",
  "tablePrefix": "server_router_",
  "heartbeatIntervalSeconds": 5,
  "offlineTimeoutSeconds": 15
}

mods/ServerRouter/config.json

WHAT IT DOES

ServerRouter uses MariaDB to share status, presence, transfers, and network modules.

IMPORTANT BEHAVIOR

All servers in the same network must point to the same database.
heartbeatIntervalSeconds controls how often the node updates its status.
offlineTimeoutSeconds determines when a node with no heartbeat is considered unavailable.

CHAPTER 03 · 1 EXAMPLES

Routes and commands

Define destinations, commands, aliases, permissions, and route messages.

01CONFIGURATION

Routes, commands, aliases and permissions

Each route connects a command to a destination server and is checked before transfer.

CONFIGURATION

{
  "routes": [
    {
      "name": "Survival",
      "command": "survival",
      "aliases": [
        "sopravvivenza"
      ],
      "serverId": "survival",
      "host": "survival.example.com",
      "port": 5522,
      "permission": "serverrouter.command.survival"
    }
  ]
}

mods/ServerRouter/config.json → routes[]

WHAT IT DOES

Each route connects a command to a destination server and is checked before transfer.

IMPORTANT BEHAVIOR

The command is stored without a slash in JSON and used in game as /survival.
aliases adds alternate names for the same transfer.
Before referral, ServerRouter checks destination status, capacity, and availability.

CHAPTER 04 · 1 EXAMPLES

Transfer security

Protect backend servers and control temporary authorizations, rejoin, and cooldowns.

01CONFIGURATION

Backend protection and transfer tokens

Backend servers can reject direct access and accept only players coming from an authorized transfer.

CONFIGURATION

{
  "allowDirectAccess": false,
  "allowSameServerRejoin": true,
  "sameServerRejoinSeconds": 300,
  "accessTokenTtlSeconds": 60,
  "accessTokenSecret": "",
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20,
  "loginPortalSafetySeconds": 20
}

mods/ServerRouter/config.json

WHAT IT DOES

Backend servers can reject direct access and accept only players coming from an authorized transfer.

IMPORTANT BEHAVIOR

With allowDirectAccess=false, the backend uses the temporary authorization generated by the source server.
Hytale's native whitelist remains the final authority for server access.
Arrival cooldowns prevent accidental portal bounce immediately after login or transfer.

CHAPTER 05 · 1 EXAMPLES

Portals

Use the same routes to generate travel portals consistent with network checks.

01CONFIGURATION

Portals linked to routes

Portals use destinations configured in the router and keep the same availability and security checks.

CONFIGURATION

{
  "routes": [
    {
      "name": "Dungeon",
      "command": "dungeon",
      "aliases": [],
      "serverId": "dungeon",
      "host": "dungeon.example.com",
      "port": 5521,
      "permission": "serverrouter.command.dungeon"
    }
  ],
  "portalArrivalCooldownEnabled": true,
  "portalArrivalCooldownSeconds": 20
}

mods/ServerRouter/config.json → routes[]

WHAT IT DOES

Portals use destinations configured in the router and keep the same availability and security checks.

IMPORTANT BEHAVIOR

You do not need a second destination for the portal: the route is the common source.
Portal assets are generated by the plugin and loaded as a runtime asset pack.
If the destination is offline, full, or unavailable, the transfer is blocked.

CHAPTER 06 · 1 EXAMPLES

Shared systems

Chat, events, player list, and presence API share information across all servers.

01CONFIGURATION

Global chat and events

Servers can share chat and major network events so Hub, Survival, Dungeon, Creative, and other nodes feel like parts of one network.

CONFIGURATION

{
  "networkChat": {
    "enabled": true,
    "pollSeconds": 1,
    "messageTtlSeconds": 300,
    "maxMessageLength": 300,
    "captureMode": "eliteessentials",
    "serverDisplayNames": {
      "hub": "Hub",
      "survival": "Survival",
      "creative": "Creative"
    },
    "remoteFormat": "&8[&b%server%&8] &r%chat_format%",
    "fallbackFormat": "&8[&b%server%&8] &7%player%&r: &f%message%"
  },
  "networkEvents": {
    "enabled": true,
    "pollSeconds": 1,
    "eventTtlSeconds": 300,
    "joinEnabled": true,
    "quitEnabled": true,
    "switchEnabled": true,
    "suppressServerSwitchJoinQuit": true,
    "quitDelaySeconds": 3,
    "respectVanish": true
  }
}

mods/ServerRouter/config.json

WHAT IT DOES

Servers can share chat and major network events so Hub, Survival, Dungeon, Creative, and other nodes feel like parts of one network.

IMPORTANT BEHAVIOR

Network Chat forwards player messages across participating servers while keeping the source server name and a configurable common format.
captureMode defines where local chat is captured; remoteFormat uses existing formatting when possible while fallbackFormat provides a safe alternative.
serverDisplayNames gives each server a readable name so messages can show Hub, Survival, or Creative instead of only the technical serverId.
Network Events can announce join, quit, and server switch across the network; each event type can be enabled independently.
suppressServerSwitchJoinQuit prevents a server switch from appearing as a false network quit followed by a new join.
quitDelaySeconds helps distinguish a real disconnect from an in-progress transfer; respectVanish avoids exposing hidden players when the available integration supports it.
The Network Player List and Presence API share player presence with compatible servers and mods without requiring every integration to query the database separately.

CHAPTER 07 · 2 EXAMPLES

Native scoreboard

Configure content, position, colors, logo, and overrides for worlds or dynamic instances.

01CONFIGURATION

Global scoreboard

The native scoreboard is independent and can be positioned in any of the four corners with pixel offsets.

CONFIGURATION

{
  "refreshSeconds": 10,
  "horizontal": "right:0",
  "vertical": "top:0",
  "boardWidth": 180,
  "backgroundColor": "default",
  "backgroundAlpha": 0.2,
  "logo": "hytari_logo.png",
  "logoWidth": 256,
  "logoHeight": 64,
  "maxLines": 12,
  "lines": [
    "&fOnline: &b{serverrouter_total_online} &7| &fTPS: &b{tps}",
    "&fPlayer: &b{player}",
    "&fWorld: &b{world}"
  ]
}

mods/ServerRouter/scoreboard.json

WHAT IT DOES

The native scoreboard is independent and can be positioned in any of the four corners with pixel offsets.

IMPORTANT BEHAVIOR

The native scoreboard is optional: it can be disabled without disabling ServerRouter or its network systems.
horizontal accepts left:<px> or right:<px>; vertical accepts top:<px> or bottom:<px>.
backgroundColor accepts default, none, or a HEX color #RRGGBB.
logo: none hides the logo. Lines support formatting and dynamic placeholders.
If you prefer an external scoreboard, you can use ServerRouter placeholders without showing the native one.

02CONFIGURATION

Per-world overrides and dynamic instances

A world can inherit the global configuration and override only the fields it needs.

CONFIGURATION

{
  "worlds": {
    "instance-Forgotten_Temple-*": {
      "enabled": true,
      "horizontal": "left:18",
      "vertical": "bottom:120",
      "backgroundColor": "#0E4E0D",
      "backgroundAlpha": 0.25
    },
    "creative_world": {
      "enabled": false
    }
  }
}

mods/ServerRouter/scoreboard.json → worlds

WHAT IT DOES

A world can inherit the global configuration and override only the fields it needs.

IMPORTANT BEHAVIOR

Matching is case-insensitive and supports * for instance worlds with dynamic suffixes.
Precedence: exact world name > most specific wildcard > global configuration.
An override can change position, lines, width, background, or logo without duplicating the entire global block.

CHAPTER 08 · 2 EXAMPLES

Inventory Sync and ItemQuality

Synchronize inventories safely and preserve ItemQuality across different registries.

01CONFIGURATION

Inventory Sync

Inventory synchronization is optional and uses temporary locks to protect loading, saving, and concurrent transfers.

CONFIGURATION

{
  "inventorySync": {
    "enabled": false,
    "lockTtlSeconds": 120,
    "lockRefreshSeconds": 30,
    "autoSaveEnabled": true,
    "autoSaveIntervalSeconds": 600,
    "profileSaveDelayMillis": 1500,
    "loadingInventoryMessageEnabled": true,
    "loadingInventoryMessage": "server.serverrouter.inventory.loading",
    "lockedInventoryMessage": "server.serverrouter.inventory.locked",
    "debugQualityMapping": false,
    "qualityMappingLogRetentionDays": 3
  }
}

mods/ServerRouter/config.json → inventorySync

WHAT IT DOES

Inventory synchronization is optional and uses temporary locks to protect loading, saving, and concurrent transfers.

IMPORTANT BEHAVIOR

Enable it only on servers that must share the same inventory profile.
Locks prevent concurrent access that could create duplication or overwrites.
Keep debugQualityMapping disabled during normal operation.

02CONFIGURATION

ItemQuality across different registries

ServerRouter preserves the semantic identity of qualities instead of relying only on runtime indexes.

CONFIGURATION

{
  "itemQualityMapping": {
    "enabled": false,
    "log-to-file": true,
    "log-to-console": false
  }
}

mods/ServerRouter/config.json

WHAT IT DOES

ServerRouter preserves the semantic identity of qualities instead of relying only on runtime indexes.

IMPORTANT BEHAVIOR

ItemQuality diagnostics are mainly useful when two servers have different registries or mods.
If a quality is unavailable on the destination, the system uses a safe fallback and preserves the original identity when possible.
Mapping logs are diagnostic tools and are not required for a stable network.

CHAPTER 09 · 1 EXAMPLES

Placeholders, API and diagnostics

Integrate companion mods, reload the scoreboard, and use diagnostics when needed.

01CONFIGURATION

Placeholders and API for companion mods

The scoreboard includes built-in placeholders and a public API lets other mods register new ones without patching ServerRouter.

CONFIGURATION

{
  "integrations": {
    "api": {
      "enabled": true,
      "cacheSeconds": 10
    },
    "betterScoreBoard": {
      "enabled": false,
      "registerPlaceholders": true
    }
  },
  "scoreboardExample": [
    "{player}",
    "{world}",
    "{tps}",
    "{serverrouter_total_online}",
    "{myplugin_rank}"
  ]
}

Java API + scoreboard.json

WHAT IT DOES

The scoreboard includes built-in placeholders and a public API lets other mods register new ones without patching ServerRouter.

IMPORTANT BEHAVIOR

Custom placeholders are case-insensitive and cannot steal built-in placeholders that have already been resolved.
The native scoreboard can remain disabled: ServerRouter placeholders can be registered and used by compatible external scoreboards or mods.
BetterScoreBoard is supported through the dedicated integration. If another scoreboard does not recognize the placeholders, contact us and we can evaluate specific compatibility.
The read-only Presence/Network API prevents every mod from querying the database separately.
For the native scoreboard, use /scoreboard reload after changing configuration, logo, or layout.

Before using an example

Examples are intentionally focused on one module at a time. Merge the shown properties into the corresponding file instead of replacing a complete production configuration with a partial example.

Database credentials and host names shown here are examples. Never publish real passwords or secrets, and keep the same shared database configuration only on the servers that belong to the same trusted network.

The public release uses horizontal/vertical scoreboard positioning. Legacy offsetRight/offsetTop fields from development builds are not part of the documented configuration.