HyTari Studios · Ghid oficial de configurare

Server Router

Configurează rețeaua înțelegând fiecare modul.

Un ghid practic pentru Server Router - Network Sync. Urmărește modulele de la identitatea serverului și rute până la sistemele partajate, scoreboardul nativ și sincronizarea opțională a inventarului. Fiecare secțiune combină JSON copiabil cu explicația comportamentului real.

PORNEȘTE GHIDUL PAGINA MODULUI

ÎNAINTE SĂ ÎNCEPI

Primii pași

PAS 01

Instalează pe fiecare server

Folosește aceeași build ServerRouter pe fiecare nod participant la rețea.

PAS 02

Configurează câte un nod

Dă fiecărui server un serverId unic, propriul host/port și rolul corect.

PAS 03

Testează înainte de acces public

Verifică rutele și protecția backend cu conturi staff înainte de traficul public.

ServerRouter este infrastructură de rețea: configurează cu atenție credențialele, hosturile, permisiunile și regulile de direct access. Păstrează un backup al configurației production înainte de a modifica mai multe module.

CAPITOL 01 · 1 EXEMPLE

Instalare și rol

Identifică serverul în rețea și stabilește dacă este router, backend sau ambele.

01CONFIGURAȚIE

Identitatea și rolul serverului

Fiecare nod al rețelei are nevoie de serverId unic și adresă accesibilă celorlalte servere.

CONFIGURAȚIE

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

mods/ServerRouter/config.json

CE FACE

Fiecare nod al rețelei are nevoie de serverId unic și adresă accesibilă celorlalte servere.

COMPORTAMENT IMPORTANT

role: main activează routing, backend acceptă transferuri, iar both combină rolurile.
serverId trebuie să rămână stabil și să corespundă valorii din routes și modulele de rețea.
acceptingPlayers poate scoate temporar serverul din destinații fără oprire.

CAPITOL 02 · 1 EXEMPLE

Bază de date și heartbeat

Configurează MariaDB și frecvența cu care fiecare server publică starea.

01CONFIGURAȚIE

MariaDB, heartbeat și stare online

ServerRouter folosește MariaDB pentru a partaja stare, presence, transferuri și module de rețea.

CONFIGURAȚIE

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

CE FACE

ServerRouter folosește MariaDB pentru a partaja stare, presence, transferuri și module de rețea.

COMPORTAMENT IMPORTANT

Toate serverele aceleiași rețele trebuie să folosească aceeași bază.
heartbeatIntervalSeconds stabilește frecvența actualizării stării nodului.
offlineTimeoutSeconds stabilește când un nod fără heartbeat este considerat indisponibil.

CAPITOL 03 · 1 EXEMPLE

Rute și comenzi

Definește destinații, comenzi, aliasuri, permisiuni și mesajele rutelor.

01CONFIGURAȚIE

Rute, comenzi, aliasuri și permisiuni

Fiecare rută leagă o comandă de un server destinație și este verificată înainte de transfer.

CONFIGURAȚIE

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

mods/ServerRouter/config.json → routes[]

CE FACE

Fiecare rută leagă o comandă de un server destinație și este verificată înainte de transfer.

COMPORTAMENT IMPORTANT

Comanda este stocată fără slash în JSON și folosită în joc ca /survival.
aliases adaugă nume alternative pentru același transfer.
Înainte de referral, ServerRouter verifică starea, capacitatea și disponibilitatea destinației.

CAPITOL 04 · 1 EXEMPLE

Securitatea transferurilor

Protejează backendurile și gestionează autorizări temporare, rejoin și cooldown.

01CONFIGURAȚIE

Protecție backend și tokenuri de transfer

Backendurile pot refuza acces direct și accepta doar jucători veniți prin transfer autorizat.

CONFIGURAȚIE

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

mods/ServerRouter/config.json

CE FACE

Backendurile pot refuza acces direct și accepta doar jucători veniți prin transfer autorizat.

COMPORTAMENT IMPORTANT

Cu allowDirectAccess=false, backendul folosește autorizarea temporară generată de serverul sursă.
Whitelistul nativ Hytale rămâne autoritatea finală pentru acces.
Arrival cooldown previne revenirea accidentală prin portal imediat după login sau transfer.

CAPITOL 05 · 1 EXEMPLE

Portaluri

Folosește aceleași rute pentru portaluri cu aceleași controale de rețea.

01CONFIGURAȚIE

Portaluri legate de rute

Portalurile folosesc destinațiile routerului și aceleași verificări de disponibilitate și securitate.

CONFIGURAȚIE

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

CE FACE

Portalurile folosesc destinațiile routerului și aceleași verificări de disponibilitate și securitate.

COMPORTAMENT IMPORTANT

Nu este nevoie de a doua destinație: ruta este sursa comună.
Asseturile portalurilor sunt generate de plugin și încărcate ca runtime asset pack.
Dacă destinația este offline, plină sau indisponibilă, transferul este blocat.

CAPITOL 06 · 1 EXEMPLE

Sisteme partajate

Chat, events, player list și Presence API distribuie informații între toate serverele.

01CONFIGURAȚIE

Chat și events globale

Serverele pot partaja chatul și evenimentele importante astfel încât Hub, Survival, Dungeon, Creative și alte noduri să pară o singură rețea.

CONFIGURAȚIE

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

CE FACE

Serverele pot partaja chatul și evenimentele importante astfel încât Hub, Survival, Dungeon, Creative și alte noduri să pară o singură rețea.

COMPORTAMENT IMPORTANT

Network Chat retransmite mesajele între serverele participante, păstrând numele serverului sursă și un format comun configurabil.
captureMode definește sursa chatului local; remoteFormat folosește formatarea existentă, iar fallbackFormat oferă o alternativă sigură.
serverDisplayNames atribuie nume lizibile precum Hub, Survival sau Creative în locul serverId-ului tehnic.
Network Events poate anunța join, quit și schimbarea serverului în întreaga rețea; fiecare tip se controlează separat.
suppressServerSwitchJoinQuit împiedică schimbarea serverului să apară ca fals quit + join.
quitDelaySeconds ajută la distingerea unui disconnect real de un transfer în desfășurare; respectVanish protejează jucătorii ascunși când integrarea suportă asta.
Network Player List și Presence API partajează presence cu servere și mods compatibile fără interogări separate ale bazei pentru fiecare integrare.

CAPITOL 07 · 2 EXEMPLE

Scoreboard nativ

Configurează conținut, poziție, culori, logo și override-uri pentru lumi sau instanțe dinamice.

01CONFIGURAȚIE

Scoreboard global

Scoreboardul nativ este independent și poate fi poziționat în oricare dintre cele patru colțuri cu offset în pixeli.

CONFIGURAȚIE

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

CE FACE

Scoreboardul nativ este independent și poate fi poziționat în oricare dintre cele patru colțuri cu offset în pixeli.

COMPORTAMENT IMPORTANT

Scoreboardul nativ este opțional și poate fi dezactivat fără a dezactiva ServerRouter sau sistemele de rețea.
horizontal acceptă left:<px> sau right:<px>; vertical acceptă top:<px> sau bottom:<px>.
backgroundColor acceptă default, none sau HEX #RRGGBB.
logo: none ascunde logo-ul. Liniile suportă formatare și placeholders dinamice.
Dacă preferi un scoreboard extern, poți folosi placeholders ServerRouter fără a afișa cel nativ.

02CONFIGURAȚIE

Override-uri pe lumi și instanțe dinamice

O lume poate moșteni configurația globală și modifica doar câmpurile necesare.

CONFIGURAȚIE

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

CE FACE

O lume poate moșteni configurația globală și modifica doar câmpurile necesare.

COMPORTAMENT IMPORTANT

Matchingul este case-insensitive și suportă * pentru lumi instance cu sufix dinamic.
Prioritate: nume exact al lumii > cel mai specific wildcard > configurația globală.
Un override poate modifica poziția, liniile, lățimea, fundalul sau logo-ul fără a duplica blocul global.

CAPITOL 08 · 2 EXEMPLE

Inventory Sync și ItemQuality

Sincronizează inventarele în siguranță și păstrează ItemQuality între registries diferite.

01CONFIGURAȚIE

Inventory Sync

Sincronizarea inventarului este opțională și folosește locks temporare pentru a proteja load, save și transferurile concurente.

CONFIGURAȚIE

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

CE FACE

Sincronizarea inventarului este opțională și folosește locks temporare pentru a proteja load, save și transferurile concurente.

COMPORTAMENT IMPORTANT

Activează doar pe serverele care trebuie să partajeze același profil de inventar.
Locks previn accesul concurent care ar putea cauza duplicări sau suprascrieri.
Lasă debugQualityMapping dezactivat în utilizarea normală.

02CONFIGURAȚIE

ItemQuality între registries diferite

ServerRouter păstrează identitatea semantică a calităților în loc să depindă doar de indexurile runtime.

CONFIGURAȚIE

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

mods/ServerRouter/config.json

CE FACE

ServerRouter păstrează identitatea semantică a calităților în loc să depindă doar de indexurile runtime.

COMPORTAMENT IMPORTANT

Diagnosticul ItemQuality este util mai ales când serverele folosesc registries sau mods diferite.
Dacă o calitate lipsește la destinație, sistemul folosește fallback sigur și păstrează identitatea originală când este posibil.
Mapping logs sunt instrumente de diagnostic, nu o cerință pentru o rețea stabilă.

CAPITOL 09 · 1 EXEMPLE

Placeholders, API și diagnostic

Integrează companion mods, reîncarcă scoreboardul și folosește diagnosticul când este necesar.

01CONFIGURAȚIE

Placeholders și API pentru companion mods

Scoreboardul include placeholders interne, iar API-ul public permite altor mods să înregistreze altele noi fără patch ServerRouter.

CONFIGURAȚIE

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

Java API + scoreboard.json

CE FACE

Scoreboardul include placeholders interne, iar API-ul public permite altor mods să înregistreze altele noi fără patch ServerRouter.

COMPORTAMENT IMPORTANT

Placeholders custom sunt case-insensitive și nu pot prelua placeholders interne deja rezolvate.
Scoreboardul nativ poate rămâne dezactivat; placeholders ServerRouter pot fi folosite de scoreboards sau mods externe compatibile.
BetterScoreBoard este suportat prin integrarea dedicată. Pentru alt scoreboard se poate evalua compatibilitate specifică.
Presence/Network API read-only evită interogări separate ale bazei din fiecare mod.
Pentru scoreboardul nativ folosește /scoreboard reload după schimbări de configurație, logo sau layout.

Înainte de a folosi un exemplu

Exemplele se concentrează intenționat pe câte un modul. Combină proprietățile prezentate cu fișierul corespunzător, nu înlocui o configurație production completă cu un exemplu parțial.

Credențialele bazei de date și hosturile sunt exemple. Nu publica parole sau secrets reale și folosește aceeași bază partajată doar pe serverele aceleiași rețele de încredere.

Release-ul public folosește horizontal/vertical pentru poziția scoreboardului. Câmpurile vechi offsetRight/offsetTop din buildurile de dezvoltare nu fac parte din configurația documentată.

ÎNAPOI SUS