HyTari Studios · Officiel konfigurationsguide

Server Router

Konfigurer netværket ved at forstå hvert modul.

En praktisk reference til Server Router - Network Sync. Følg modulerne fra serveridentitet og routes til delte systemer, native scoreboard og valgfri inventory sync. Hver sektion kombinerer kopierbar JSON med en forklaring af den faktiske funktion.

START GUIDEN MODSIDE

FØR DU BEGYNDER

Kom godt i gang

TRIN 01

Installer på alle servere

Brug samme ServerRouter-build på alle noder i netværket.

TRIN 02

Konfigurer én node ad gangen

Giv hver server et unikt serverId, eget host/port og korrekt rolle.

TRIN 03

Test før offentlig adgang

Kontrollér routes og backend-beskyttelse med staff-konti før offentlig trafik.

ServerRouter er netværksinfrastruktur: konfigurer credentials, hosts, tilladelser og direct-access-regler bevidst. Gem en backup af produktionskonfigurationen før flere moduler ændres.

KAPITEL 01 · 1 EKSEMPLER

Installation og rolle

Identificer serveren i netværket og vælg router, backend eller begge.

01KONFIGURATION

Serveridentitet og rolle

Hver node kræver et unikt serverId og en adresse, som de andre servere kan nå.

KONFIGURATION

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

mods/ServerRouter/config.json

HVAD DET GØR

Hver node kræver et unikt serverId og en adresse, som de andre servere kan nå.

VIGTIG ADFÆRD

role: main aktiverer routing, backend modtager transfers, og both kombinerer rollerne.
serverId skal være stabilt og matche værdien i routes og netværksmoduler.
acceptingPlayers kan midlertidigt fjerne en server fra destinationer uden at slukke den.

KAPITEL 02 · 1 EKSEMPLER

Database og heartbeat

Konfigurer MariaDB og hvor ofte hver server offentliggør status.

01KONFIGURATION

MariaDB, heartbeat og online-status

ServerRouter bruger MariaDB til at dele status, presence, transfers og netværksmoduler.

KONFIGURATION

{
  "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

HVAD DET GØR

ServerRouter bruger MariaDB til at dele status, presence, transfers og netværksmoduler.

VIGTIG ADFÆRD

Alle servere i samme netværk skal bruge samme database.
heartbeatIntervalSeconds styrer hvor ofte noden opdaterer status.
offlineTimeoutSeconds afgør hvornår en node uden heartbeat regnes som utilgængelig.

KAPITEL 03 · 1 EKSEMPLER

Routes og kommandoer

Definer destinationer, kommandoer, aliases, tilladelser og route-beskeder.

01KONFIGURATION

Routes, kommandoer, aliases og tilladelser

Hver route forbinder en kommando med en destinationsserver og kontrolleres før transfer.

KONFIGURATION

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

mods/ServerRouter/config.json → routes[]

HVAD DET GØR

Hver route forbinder en kommando med en destinationsserver og kontrolleres før transfer.

VIGTIG ADFÆRD

Kommandoen gemmes uden slash i JSON og bruges i spillet som /survival.
aliases tilføjer alternative navne til samme transfer.
Før referral kontrollerer ServerRouter status, kapacitet og tilgængelighed.

KAPITEL 04 · 1 EKSEMPLER

Transfersikkerhed

Beskyt backends og styr midlertidige autorisationer, rejoin og cooldowns.

01KONFIGURATION

Backend-beskyttelse og transfer-tokens

Backends kan afvise direkte adgang og kun acceptere spillere fra autoriserede transfers.

KONFIGURATION

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

mods/ServerRouter/config.json

HVAD DET GØR

Backends kan afvise direkte adgang og kun acceptere spillere fra autoriserede transfers.

VIGTIG ADFÆRD

Med allowDirectAccess=false bruges den midlertidige autorisation fra kildeserveren.
Hytales native whitelist er fortsat sidste autoritet for adgang.
Arrival-cooldowns forhindrer utilsigtet portal-bounce lige efter login eller transfer.

KAPITEL 05 · 1 EKSEMPLER

Portaler

Brug de samme routes til rejseportaler med samme netværkskontroller.

01KONFIGURATION

Portaler knyttet til routes

Portaler bruger routerens destinationer og samme checks for tilgængelighed og sikkerhed.

KONFIGURATION

{
  "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[]

HVAD DET GØR

Portaler bruger routerens destinationer og samme checks for tilgængelighed og sikkerhed.

VIGTIG ADFÆRD

Der kræves ingen ekstra destination: routen er den fælles kilde.
Portal-assets genereres af plugin'et og indlæses som runtime asset pack.
Hvis destinationen er offline, fuld eller utilgængelig, blokeres transfer.

KAPITEL 06 · 1 EKSEMPLER

Delte systemer

Chat, events, player list og Presence API deler information mellem alle servere.

01KONFIGURATION

Global chat og events

Serverne kan dele chat og vigtige events, så Hub, Survival, Dungeon, Creative og andre noder opleves som ét netværk.

KONFIGURATION

{
  "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

HVAD DET GØR

Serverne kan dele chat og vigtige events, så Hub, Survival, Dungeon, Creative og andre noder opleves som ét netværk.

VIGTIG ADFÆRD

Network Chat videresender beskeder mellem deltagende servere med kildeserverens navn og et fælles konfigurerbart format.
captureMode vælger kilden til lokal chat; remoteFormat bruger eksisterende formatering, fallbackFormat giver et sikkert alternativ.
serverDisplayNames giver læsbare navne som Hub, Survival eller Creative i stedet for teknisk serverId.
Network Events kan annoncere join, quit og serverskift på tværs af netværket; hver type kan styres separat.
suppressServerSwitchJoinQuit forhindrer serverskift i at ligne et falsk quit efterfulgt af join.
quitDelaySeconds skelner ægte disconnect fra igangværende transfer; respectVanish skjuler skjulte spillere, når integrationen understøtter det.
Network Player List og Presence API deler presence uden at hver integration behøver separate databaseforespørgsler.

KAPITEL 07 · 2 EKSEMPLER

Native scoreboard

Konfigurer indhold, placering, farver, logo og overrides for worlds eller dynamiske instances.

01KONFIGURATION

Global scoreboard

Den native scoreboard er uafhængig og kan placeres i et af fire hjørner med pixel-offsets.

KONFIGURATION

{
  "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

HVAD DET GØR

Den native scoreboard er uafhængig og kan placeres i et af fire hjørner med pixel-offsets.

VIGTIG ADFÆRD

Den native scoreboard er valgfri og kan slås fra uden at deaktivere ServerRouter eller netværksfunktionerne.
horizontal accepterer left:<px> eller right:<px>; vertical accepterer top:<px> eller bottom:<px>.
backgroundColor accepterer default, none eller HEX #RRGGBB.
logo: none skjuler logoet. Linjer understøtter formatering og dynamiske placeholders.
Eksterne scoreboards kan bruge ServerRouter-placeholders uden at vise den native scoreboard.

02KONFIGURATION

Overrides pr. world og dynamiske instances

Et world kan arve global konfiguration og kun ændre nødvendige felter.

KONFIGURATION

{
  "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

HVAD DET GØR

Et world kan arve global konfiguration og kun ændre nødvendige felter.

VIGTIG ADFÆRD

Matching er case-insensitive og understøtter * for instances med dynamisk suffix.
Prioritet: eksakt world-navn > mest specifik wildcard > global konfiguration.
Et override kan ændre placering, linjer, bredde, baggrund eller logo uden at duplikere hele blokken.

KAPITEL 08 · 2 EKSEMPLER

Inventory Sync og ItemQuality

Synkroniser inventories sikkert og bevar ItemQuality mellem forskellige registries.

01KONFIGURATION

Inventory Sync

Inventory sync er valgfri og bruger midlertidige locks til load, save og samtidige transfers.

KONFIGURATION

{
  "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

HVAD DET GØR

Inventory sync er valgfri og bruger midlertidige locks til load, save og samtidige transfers.

VIGTIG ADFÆRD

Aktivér kun på servere, der skal dele samme inventory-profil.
Locks forhindrer samtidige adgangsforsøg, der kan give duplication eller overskrivning.
Lad debugQualityMapping være slået fra ved normal drift.

02KONFIGURATION

ItemQuality mellem forskellige registries

ServerRouter bevarer kvaliteters semantiske identitet i stedet for kun runtime-indekser.

KONFIGURATION

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

mods/ServerRouter/config.json

HVAD DET GØR

ServerRouter bevarer kvaliteters semantiske identitet i stedet for kun runtime-indekser.

VIGTIG ADFÆRD

ItemQuality-diagnostik er især nyttig ved forskellige registries eller mods.
Hvis en kvalitet mangler på destinationen, bruges et sikkert fallback, mens original identitet bevares når muligt.
Mappinglogs er diagnostik og ikke nødvendige på et stabilt netværk.

KAPITEL 09 · 1 EKSEMPLER

Placeholders, API og diagnostik

Integrer companion mods, genindlæs scoreboard og brug diagnostik ved behov.

01KONFIGURATION

Placeholders og API til companion mods

Scoreboard har interne placeholders, og en offentlig API lader andre mods registrere nye uden patching.

KONFIGURATION

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

Java API + scoreboard.json

HVAD DET GØR

Scoreboard har interne placeholders, og en offentlig API lader andre mods registrere nye uden patching.

VIGTIG ADFÆRD

Custom placeholders er case-insensitive og kan ikke overtage allerede opløste interne placeholders.
Den native scoreboard kan være slukket; ServerRouter-placeholders kan bruges af kompatible eksterne scoreboards eller mods.
BetterScoreBoard understøttes via en dedikeret integration. For andre scoreboards kan specifik kompatibilitet vurderes.
Den read-only Presence/Network API forhindrer separate databaseforespørgsler fra hver mod.
Brug /scoreboard reload efter ændringer i konfiguration, logo eller layout.

Før du bruger et eksempel

Eksemplerne fokuserer bevidst på ét modul ad gangen. Flet de viste egenskaber ind i den relevante fil i stedet for at erstatte en komplet produktionskonfiguration med et delvist eksempel.

Databaseoplysninger og hosts er eksempler. Del aldrig rigtige adgangskoder eller secrets, og brug kun samme database mellem servere i det samme betroede netværk.

Den offentlige release bruger horizontal/vertical til scoreboard-positionering. De gamle offsetRight/offsetTop-felter fra udviklingsbuilds er ikke en del af den dokumenterede konfiguration.

TIL TOPPEN