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.

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.

01 · SERVER ROUTER

Folder and installation

File structure, backups and generated data.

mods/ServerRouter/
cache/Internal runtime data and generated configuration.
images/Custom scoreboard images and logos.
logs/Diagnostic logs when enabled.
Server/Generated game assets for portals and languages.
database.jsonShared MariaDB connection.
inventory-sync.jsonProfile synchronization and locks.
logging.jsonDiagnostic options.
network.jsonChat, events and player list.
router.jsonRoutes, access and portals.
scoreboard.jsonScoreboard and APIs.
hudvisibility.yamlAuxiliary HUD visibility settings.
manifest.jsonGenerated asset manifest.

Back up the entire folder before upgrading. Do not edit cache/runtime-config.json: it is generated. Install the same JAR on every node.

02 · SERVER ROUTER

database.json

Shared MariaDB connection across nodes.

JSON configuration
{

  "host": "127.0.0.1",

  "port": 3306,

  "name": "hytale_network",

  "user": "serverrouter",

  "password": "CHANGE_ME",

  "tablePrefix": "server_router_"

}

mods/ServerRouter/database.json

Every configuration parameter (6)

"host": "127.0.0.1",

MariaDB hostname reachable from this node.

"port": 3306,

Database TCP port, not the game port.

"name": "hytale_network",

Database name shared by the network.

"user": "serverrouter",

MariaDB account granted access to the tables.

"password": "CHANGE_ME",

MariaDB password: keep it private.

"tablePrefix": "server_router_",

Database table prefix; match across nodes sharing data.

03 · SERVER ROUTER

inventory-sync.json

Locks, autosave, profiles and ItemQuality.

JSON configuration
{

  "enabled": false,

  "lockTtlSeconds": 120,

  "lockRefreshSeconds": 30,

  "autoSaveEnabled": true,

  "autoSaveIntervalSeconds": 600,

  "profileSaveDelayMillis": 1500,

  "loadingInventoryMessageEnabled": true,

  "loadingInventoryMessage": "server.serverrouter.inventory.loading",

  "lockedInventoryMessage": "server.serverrouter.inventory.locked"

}

mods/ServerRouter/inventory-sync.json

Every configuration parameter (9)

"enabled": false,

Enables or disables only its containing module/feature.

"lockTtlSeconds": 120,

Profile lock lifetime in seconds; allows an unrefreshed lock to expire.

"lockRefreshSeconds": 30,

Interval in seconds for renewing an active lock.

"autoSaveEnabled": true,

Enables periodic synchronized-profile saves.

"autoSaveIntervalSeconds": 600,

Seconds between automatic saves.

"profileSaveDelayMillis": 1500,

Delay before profile save, in milliseconds.

"loadingInventoryMessageEnabled": true,

Shows/hides the profile loading message.

"loadingInventoryMessage": "server.serverrouter.inventory.loading",

Localization key for the loading message.

"lockedInventoryMessage": "server.serverrouter.inventory.locked",

Localization key for the locked-profile message.

Advice: keep lockRefreshSeconds substantially below lockTtlSeconds so the lock can renew before expiry. The example uses 30 and 120 seconds; consider database latency and concurrent sessions before changing them. Enable InventorySync only on nodes sharing profiles.
04 · SERVER ROUTER

logging.json

Diagnostics and log retention.

JSON configuration
{

  "transfer": {

    "enabled": false,

    "logToFile": false,

    "logToConsole": false,

    "slowSetupSeconds": 15,

    "retentionDays": 3

  },

  "itemQualityMapping": {

    "enabled": false,

    "log-to-file": true,

    "log-to-console": false,

    "retentionDays": 3

  }

}

mods/ServerRouter/logging.json

Every configuration parameter (9)

"enabled": false,

Enables or disables only its containing module/feature.

"logToFile": false,

Writes this category to a log file.

"logToConsole": false,

Shows this diagnostic category in the console.

"slowSetupSeconds": 15,

Seconds before a setup is reported as slow.

"retentionDays": 3,

Log retention in days.

"enabled": false,

Enables or disables only its containing module/feature.

"log-to-file": true,

Enables ItemQuality file logging (legacy key spelling).

"log-to-console": false,

Enables ItemQuality console logging (legacy key spelling).

"retentionDays": 3,

Log retention in days.

05 · SERVER ROUTER

network.json

Chat, events and player presence.

01 · Network chat

JSON configuration
{

  "networkChat": {

    "enabled": false,

    "pollSeconds": 1,

    "messageTtlSeconds": 300,

    "maxMessageLength": 300,

    "captureMode": "eliteessentials",

    "serverDisplayNames": {

      "hub": "Hub",

      "survival": "Survival"

    },

    "remoteFormat": "&8[&b%server%&8] &r%chat_format%",

    "fallbackFormat": "&8[&b%server%&8] &7%player%&r: &f%message%"

  }

}

mods/ServerRouter/network.json

Every configuration parameter (9)

"enabled": false,

Enables or disables only its containing module/feature.

"pollSeconds": 1,

Polling interval in seconds for shared updates.

"messageTtlSeconds": 300,

Shared chat message lifetime in seconds.

"maxMessageLength": 300,

Maximum network chat message length.

"captureMode": "eliteessentials",

Local chat capture mode; eliteessentials uses that integration.

"hub": "Hub",

Configuration value for networkChat.serverDisplayNames.hub.

"survival": "Survival",

Configuration value for networkChat.serverDisplayNames.survival.

"remoteFormat": "&8[&b%server%&8] &r%chat_format%",

Remote chat format; %chat_format% inserts original formatting when available.

"fallbackFormat": "&8[&b%server%&8] &7%player%&r: &f%message%",

Fallback chat format when original formatting is unavailable.

02 · Network events

JSON configuration
{

  "networkEvents": {

    "enabled": false,

    "pollSeconds": 1,

    "eventTtlSeconds": 300,

    "joinEnabled": true,

    "quitEnabled": true,

    "switchEnabled": true,

    "suppressServerSwitchJoinQuit": true,

    "quitDelaySeconds": 3,

    "respectVanish": true,

    "serverDisplayNames": {

      "hub": "Hub",

      "survival": "Survival"

    },

    "joinFormat": "&8[&b%server%&8] &a+ &7%player%",

    "quitFormat": "&8[&b%server%&8] &c- &7%player%",

    "switchFormat": "&8[&b%from_server% &7→ &b%to_server%&8] &7%player%"

  }

}

mods/ServerRouter/network.json

Every configuration parameter (14)

"enabled": false,

Enables or disables only its containing module/feature.

"pollSeconds": 1,

Polling interval in seconds for shared updates.

"eventTtlSeconds": 300,

Shared event lifetime in seconds.

"joinEnabled": true,

Enables network join events.

"quitEnabled": true,

Enables network quit events.

"switchEnabled": true,

Enables server-switch events.

"suppressServerSwitchJoinQuit": true,

Suppresses duplicate join/quit announcements during transfers.

"quitDelaySeconds": 3,

Seconds used to distinguish actual quits from transfers.

"respectVanish": true,

Hides vanished players where the integration supports it.

"hub": "Hub",

Configuration value for networkEvents.serverDisplayNames.hub.

"survival": "Survival",

Configuration value for networkEvents.serverDisplayNames.survival.

"joinFormat": "&8[&b%server%&8] &a+ &7%player%",

Text and placeholders for a join event.

"quitFormat": "&8[&b%server%&8] &c- &7%player%",

Text and placeholders for a quit event.

"switchFormat": "&8[&b%from_server% &7→ &b%to_server%&8] &7%player%",

Text and placeholders for a server switch.

03 · Player list

JSON configuration
{

  "networkPlayerList": {

    "enabled": true,

    "format": "%player%",

    "respectVanish": true,

    "includeLocalPlayers": true,

    "refreshSeconds": 2,

    "presenceTimeoutSeconds": 10,

    "serverShortNames": {

      "hub": "H",

      "survival": "S"

    }

  }

}

mods/ServerRouter/network.json

Every configuration parameter (8)

"enabled": true,

Enables or disables only its containing module/feature.

"format": "%player%",

Player display format in the network list.

"respectVanish": true,

Hides vanished players where the integration supports it.

"includeLocalPlayers": true,

Includes players from the current node.

"refreshSeconds": 2,

Refresh interval for this feature in seconds.

"presenceTimeoutSeconds": 10,

Seconds until an unrefreshed player presence expires.

"hub": "H",

Configuration value for networkPlayerList.serverShortNames.hub.

"survival": "S",

Configuration value for networkPlayerList.serverShortNames.survival.

Remote chat: captureMode=eliteessentials uses local EliteEssentials formatting; remoteFormat includes %chat_format% and fallbackFormat covers unavailable formatting. Verify in game after updates.
06 · SERVER ROUTER

router.json

Node identity, routes, security, whitelists and portals.

01 · Local node and general settings

JSON configuration
{

  "enabled": true,

  "server": {

    "serverId": "hub",

    "name": "Hub",

    "command": "hub",

    "aliases": [],

    "permission": "serverrouter.command.hub",

    "host": "hub.example.com",

    "port": 5520,

    "maxPlayers": 100,

    "acceptingPlayers": true,

    "heartbeat": {

      "intervalSeconds": 5,

      "offlineTimeoutSeconds": 15

    },

    "routing": {

      "allowDirectAccess": true,

      "allowSameServerRejoin": true,

      "sameServerRejoinSeconds": 300

    },

    "access": {

      "accessTokenTtlSeconds": 60,

      "accessTokenSecret": "CHANGE_TO_SAME_STRONG_SECRET_ON_ALL_NODES",

      "accessDeniedMessage": "server.serverrouter.access.denied"

    },

    "portal": {

      "portalArrivalCooldownEnabled": true,

      "portalArrivalCooldownSeconds": 20,

      "loginPortalSafetySeconds": 20

    },

    "messages": {

      "checkingMessage": "server.serverrouter.route.checking",

      "connectingMessage": "server.serverrouter.route.connecting",

      "unavailableMessage": "server.serverrouter.route.unavailable",

      "alreadyConnectedMessage": "server.serverrouter.route.already_connected",

      "portalSafetyMessage": "server.serverrouter.route.portal_safety"

    }

  },

  "languages": {

    "en-US": {

      "enable": true

    },

    "it-IT": {

      "enable": true

    }

  }

}

mods/ServerRouter/router.json

Every configuration parameter (28)

"enabled": true,

Enables or disables only its containing module/feature.

"serverId": "hub",

Stable, unique node ID; must match destinations.

"name": "Hub",

Database name shared by the network.

"command": "hub",

Command name without / used to reach the node.

"aliases": [],

Alternative commands for the same destination.

"permission": "serverrouter.command.hub",

Permission required to use the transfer command.

"host": "hub.example.com",

MariaDB hostname reachable from this node.

"port": 5520,

Database TCP port, not the game port.

"maxPlayers": 100,

Node player capacity used for availability/status checks.

"acceptingPlayers": true,

When false, removes node from available destinations without stopping it.

"intervalSeconds": 5,

Seconds between server heartbeats.

"offlineTimeoutSeconds": 15,

Seconds without heartbeat before a node is considered offline.

"allowDirectAccess": true,

When false, restricts unauthorized direct backend access.

"allowSameServerRejoin": true,

Allows controlled rejoining of the same node.

"sameServerRejoinSeconds": 300,

Controlled same-server rejoin window in seconds.

"accessTokenTtlSeconds": 60,

Referral authorization token lifetime in seconds.

"accessTokenSecret": "CHANGE_TO_SAME_STRONG_SECRET_ON_ALL_NODES",

Shared referral validation secret: use the same strong value across nodes.

"accessDeniedMessage": "server.serverrouter.access.denied",

Localization key for denied access.

"portalArrivalCooldownEnabled": true,

Enables post-arrival portal bounce protection.

"portalArrivalCooldownSeconds": 20,

Cooldown seconds after arrival.

"loginPortalSafetySeconds": 20,

Safety period in seconds after login before portal activation.

"checkingMessage": "server.serverrouter.route.checking",

Message key while checking a destination.

"connectingMessage": "server.serverrouter.route.connecting",

Message key while connecting.

"unavailableMessage": "server.serverrouter.route.unavailable",

Message key for unavailable destination.

"alreadyConnectedMessage": "server.serverrouter.route.already_connected",

Message key when already on the destination.

"portalSafetyMessage": "server.serverrouter.route.portal_safety",

Message key for portal safety.

"enable": true,

Enables the corresponding client language.

"enable": true,

Enables the corresponding client language.

02 · Routes to other servers

JSON configuration
{

  "routes": [

    {

      "serverId": "survival",

      "name": "Survival",

      "command": "survival",

      "aliases": [

        "s"

      ],

      "host": "survival.example.com",

      "port": 5521,

      "permission": "serverrouter.command.survival",

      "messages": {

        "checkingMessage": "server.serverrouter.route.checking",

        "connectingMessage": "server.serverrouter.route.connecting",

        "unavailableMessage": "server.serverrouter.route.unavailable",

        "alreadyConnectedMessage": "server.serverrouter.route.already_connected",

        "portalSafetyMessage": "server.serverrouter.route.portal_safety"

      }

    }

  ]

}

mods/ServerRouter/router.json

Every configuration parameter (13)

"routes": [{"serverId":"survival","name":"Survival","command":"survival","aliases":["s"],"host":"survival.example.com","port":5521,"permission":"serverrouter.command.survival","messages":{"checkingMessage":"server.serverrouter.route.checking","connectingMessage":"server.serverrouter.route.connecting","unavailableMessage":"server.serverrouter.route.unavailable","alreadyConnectedMessage":"server.serverrouter.route.already_connected","portalSafetyMessage":"server.serverrouter.route.portal_safety"}}],

Configuration value for routes.

"serverId": "survival",

Stable, unique node ID; must match destinations.

"name": "Survival",

Database name shared by the network.

"command": "survival",

Command name without / used to reach the node.

"aliases": ["s"],

Alternative commands for the same destination.

"host": "survival.example.com",

MariaDB hostname reachable from this node.

"port": 5521,

Database TCP port, not the game port.

"permission": "serverrouter.command.survival",

Permission required to use the transfer command.

"checkingMessage": "server.serverrouter.route.checking",

Message key while checking a destination.

"connectingMessage": "server.serverrouter.route.connecting",

Message key while connecting.

"unavailableMessage": "server.serverrouter.route.unavailable",

Message key for unavailable destination.

"alreadyConnectedMessage": "server.serverrouter.route.already_connected",

Message key when already on the destination.

"portalSafetyMessage": "server.serverrouter.route.portal_safety",

Message key for portal safety.

Security: protect backends with allowDirectAccess=false and verify destination whitelist. Use the same strong accessTokenSecret on each node. server.heartbeat controls online status and server.portal manages cooldowns.
07 · SERVER ROUTER

scoreboard.json

Integrations, placeholders and native HUD.

JSON configuration
{

  "externalScoreboard": {

    "betterScoreBoard": {

      "enabled": false,

      "registerPlaceholders": true

    }

  },

  "api": {

    "enabled": true,

    "cacheSeconds": 10

  },

  "nativeScoreboard": {

    "enabled": false,

    "refreshSeconds": 1,

    "horizontal": "right:0",

    "vertical": "top:0",

    "boardWidth": 280,

    "backgroundColor": "#0b1220",

    "backgroundAlpha": 0.82,

    "logo": "default",

    "logoWidth": 256,

    "logoHeight": 64,

    "maxLines": 12,

    "lines": [

      "&bServer: &f{server}",

      "&7Online: &f{serverrouter_total_online}"

    ],

    "worlds": {

      "instance-Forgotten_Temple-*": {

        "enabled": true,

        "horizontal": "left:18",

        "vertical": "bottom:120",

        "logo": "none"

      }

    }

  }

}

mods/ServerRouter/scoreboard.json

Every configuration parameter (20)

"enabled": false,

Enables or disables only its containing module/feature.

"registerPlaceholders": true,

Registers placeholders with BetterScoreBoard when integration is on.

"enabled": true,

Enables or disables only its containing module/feature.

"cacheSeconds": 10,

API/placeholder cache lifetime in seconds.

"enabled": false,

Enables or disables only its containing module/feature.

"refreshSeconds": 1,

Refresh interval for this feature in seconds.

"horizontal": "right:0",

Horizontal anchor and offset: left:pixels or right:pixels.

"vertical": "top:0",

Vertical anchor and offset: top:pixels or bottom:pixels.

"boardWidth": 280,

Scoreboard width in pixels.

"backgroundColor": "#0b1220",

default, none or hexadecimal #RRGGBB color.

"backgroundAlpha": 0.82,

Background opacity from 0 (transparent) to 1 (opaque).

"logo": "default",

Logo to display; none hides it and default uses the built-in logo.

"logoWidth": 256,

Logo width in pixels.

"logoHeight": 64,

Logo height in pixels.

"maxLines": 12,

Maximum number of displayed lines.

"lines": ["&bServer: &f{server}","&7Online: &f{serverrouter_total_online}"],

Ordered scoreboard lines and placeholders.

"enabled": true,

Enables or disables only its containing module/feature.

"horizontal": "left:18",

Horizontal anchor and offset: left:pixels or right:pixels.

"vertical": "bottom:120",

Vertical anchor and offset: top:pixels or bottom:pixels.

"logo": "none",

Logo to display; none hides it and default uses the built-in logo.

08 · SERVER ROUTER

Final notes

Migration and troubleshooting.

The first startup migrates legacy configurations. Back up before upgrading. Example credentials and addresses must be replaced.

All nodes in one network must share database and transfer secret. Generated cache files are not public configuration. For chat issues inspect captureMode and EliteEssentials format; for InventorySync inspect lock lifetime and refresh.

Note: router.json shows only two languages and one route for readability. Keep all languages and routes needed in your generated file.