HyTari Studios · Guida ufficiale alla configurazione

Server Router

Configura la rete capendo davvero ogni modulo.

Una guida pratica a Server Router - Network Sync. Segui i moduli dall'identità del server e dalle route fino ai sistemi condivisi, alla scoreboard nativa e alla sincronizzazione opzionale dell'inventario. Ogni sezione affianca JSON copiabile a una spiegazione di ciò che le impostazioni fanno realmente.

INIZIA LA GUIDA PAGINA MOD

PRIMA DI INIZIARE

Per iniziare

PASSO 01

Installa su ogni server

Usa la stessa build di ServerRouter su ogni nodo che partecipa alla rete.

PASSO 02

Configura un nodo alla volta

Assegna a ogni server un serverId univoco, il proprio host/port e il ruolo corretto.

PASSO 03

Testa prima di aprire gli accessi

Verifica route e protezione backend con account staff prima di usarli per il traffico pubblico.

ServerRouter è infrastruttura di rete: configura con attenzione credenziali, host, permessi e regole di accesso diretto. Conserva un backup della configurazione di produzione prima di modificare più moduli insieme.

CAPITOLO 01 · 1 ESEMPI

Installazione e ruolo

Identifica il server nella rete e stabilisci se agisce come router, backend o entrambi.

01CONFIGURAZIONE

Identità e ruolo del server

Ogni nodo della rete deve avere un serverId univoco e un indirizzo raggiungibile dagli altri server.

CONFIGURAZIONE

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

mods/ServerRouter/config.json

COSA FA

Ogni nodo della rete deve avere un serverId univoco e un indirizzo raggiungibile dagli altri server.

COMPORTAMENTO IMPORTANTE

role: main abilita le funzioni di instradamento, backend accetta i trasferimenti, both combina i due ruoli.
serverId deve essere stabile e uguale al valore usato nelle route e nei moduli di rete.
acceptingPlayers può escludere temporaneamente un server dalle destinazioni senza spegnerlo.

CAPITOLO 02 · 1 ESEMPI

Database e heartbeat

Configura MariaDB e i tempi con cui ogni server pubblica il proprio stato.

01CONFIGURAZIONE

MariaDB, heartbeat e stato online

ServerRouter usa MariaDB per condividere stato, presenze, trasferimenti e moduli di rete.

CONFIGURAZIONE

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

COSA FA

ServerRouter usa MariaDB per condividere stato, presenze, trasferimenti e moduli di rete.

COMPORTAMENTO IMPORTANTE

Tutti i server della stessa rete devono puntare allo stesso database.
heartbeatIntervalSeconds stabilisce quanto spesso il nodo aggiorna il proprio stato.
offlineTimeoutSeconds determina dopo quanto tempo un nodo senza heartbeat viene considerato non disponibile.

CAPITOLO 03 · 1 ESEMPI

Route e comandi

Definisci destinazioni, comandi, alias, permessi e messaggi delle route.

01CONFIGURAZIONE

Route, comandi, alias e permessi

Ogni route collega un comando a un server di destinazione e viene controllata prima del trasferimento.

CONFIGURAZIONE

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

mods/ServerRouter/config.json → routes[]

COSA FA

Ogni route collega un comando a un server di destinazione e viene controllata prima del trasferimento.

COMPORTAMENTO IMPORTANTE

Il comando viene registrato senza slash nel JSON e usato in gioco come /survival.
aliases aggiunge nomi alternativi allo stesso trasferimento.
Prima del referral ServerRouter verifica stato, capacità e disponibilità del server di destinazione.

CAPITOLO 04 · 1 ESEMPI

Sicurezza dei trasferimenti

Proteggi i backend e regola autorizzazioni temporanee, rejoin e cooldown.

01CONFIGURAZIONE

Backend protection e token di trasferimento

I backend possono rifiutare accessi diretti e accettare soltanto giocatori provenienti da un trasferimento autorizzato.

CONFIGURAZIONE

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

mods/ServerRouter/config.json

COSA FA

I backend possono rifiutare accessi diretti e accettare soltanto giocatori provenienti da un trasferimento autorizzato.

COMPORTAMENTO IMPORTANTE

Con allowDirectAccess=false il backend usa l'autorizzazione temporanea generata dal server sorgente.
La whitelist nativa di Hytale resta l'autorità finale per l'accesso al server.
I cooldown di arrivo evitano rimbalzi involontari attraverso portali immediatamente dopo login o trasferimento.

CAPITOLO 05 · 1 ESEMPI

Portali

Usa le stesse route per generare portali di viaggio coerenti con i controlli di rete.

01CONFIGURAZIONE

Portali collegati alle route

I portali usano le destinazioni configurate nel router e mantengono gli stessi controlli di disponibilità e sicurezza.

CONFIGURAZIONE

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

COSA FA

I portali usano le destinazioni configurate nel router e mantengono gli stessi controlli di disponibilità e sicurezza.

COMPORTAMENTO IMPORTANTE

Non serve creare una seconda destinazione separata per il portale: la route è la fonte comune.
Gli asset dei portali vengono generati dal plugin e caricati come runtime asset pack.
Se la destinazione è offline, piena o non disponibile il trasferimento viene bloccato.

CAPITOLO 06 · 1 ESEMPI

Sistemi condivisi

Chat, eventi, player list e API di presenza condividono informazioni tra tutti i server.

01CONFIGURAZIONE

Chat ed eventi globali

I server possono condividere la chat e gli eventi principali della rete, così i giocatori percepiscono Hub, Survival, Dungeon, Creative e gli altri nodi come parti dello stesso network.

CONFIGURAZIONE

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

COSA FA

I server possono condividere la chat e gli eventi principali della rete, così i giocatori percepiscono Hub, Survival, Dungeon, Creative e gli altri nodi come parti dello stesso network.

COMPORTAMENTO IMPORTANTE

Network Chat inoltra sui server partecipanti i messaggi dei giocatori, mantenendo il nome del server di provenienza e un formato comune configurabile.
captureMode definisce da quale sistema viene acquisita la chat locale; remoteFormat usa la formattazione già disponibile quando possibile, mentre fallbackFormat fornisce un formato sicuro alternativo.
serverDisplayNames assegna un nome leggibile a ogni server, così nei messaggi puoi mostrare Hub, Survival o Creative invece del solo serverId tecnico.
Network Events può annunciare join, quit e cambio server a tutta la rete. Ogni tipo di evento può essere abilitato o disabilitato separatamente.
suppressServerSwitchJoinQuit evita che il passaggio da un server all'altro venga mostrato come una falsa uscita dalla rete seguita da un nuovo ingresso.
quitDelaySeconds aiuta a distinguere una vera disconnessione da un trasferimento ancora in corso; respectVanish evita di esporre giocatori nascosti quando l'integrazione disponibile lo consente.
La Network Player List e la Presence API condividono la presenza dei giocatori con server e mod compatibili senza richiedere a ogni integrazione di interrogare separatamente il database.

CAPITOLO 07 · 2 ESEMPI

Scoreboard nativa

Configura contenuto, posizione, colori, logo e override per mondi o istanze dinamiche.

01CONFIGURAZIONE

Scoreboard globale

La scoreboard nativa è indipendente e può essere posizionata in uno dei quattro angoli con offset in pixel.

CONFIGURAZIONE

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

COSA FA

La scoreboard nativa è indipendente e può essere posizionata in uno dei quattro angoli con offset in pixel.

COMPORTAMENTO IMPORTANTE

La scoreboard nativa è opzionale: può essere disattivata senza disattivare ServerRouter o i suoi sistemi di rete.
horizontal accetta left:<px> o right:<px>; vertical accetta top:<px> o bottom:<px>.
backgroundColor accetta default, none oppure un colore HEX #RRGGBB.
logo: none nasconde il logo. Le righe supportano formattazione e placeholder dinamici.
Se preferisci una scoreboard esterna, puoi usare i placeholder di ServerRouter senza mostrare quella nativa.

02CONFIGURAZIONE

Override per mondo e istanze dinamiche

Un mondo può ereditare la configurazione globale e modificare soltanto i campi necessari.

CONFIGURAZIONE

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

COSA FA

Un mondo può ereditare la configurazione globale e modificare soltanto i campi necessari.

COMPORTAMENTO IMPORTANTE

Il matching è case-insensitive e supporta * per mondi istanza con suffisso dinamico.
Precedenza: nome esatto > wildcard più specifica > configurazione globale.
Un override può cambiare posizione, righe, larghezza, sfondo o logo senza duplicare tutto il blocco globale.

CAPITOLO 08 · 2 ESEMPI

Inventory Sync e ItemQuality

Sincronizza inventari in sicurezza e conserva le ItemQuality anche tra registry differenti.

01CONFIGURAZIONE

Inventory Sync

La sincronizzazione inventario è opzionale e usa lock temporanei per proteggere caricamento, salvataggio e trasferimenti concorrenti.

CONFIGURAZIONE

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

COSA FA

La sincronizzazione inventario è opzionale e usa lock temporanei per proteggere caricamento, salvataggio e trasferimenti concorrenti.

COMPORTAMENTO IMPORTANTE

Attivala soltanto sui server che devono condividere lo stesso profilo inventario.
I lock impediscono accessi concorrenti che potrebbero creare duplicazioni o sovrascritture.
debugQualityMapping va lasciato disattivato durante il normale utilizzo.

02CONFIGURAZIONE

ItemQuality tra registry differenti

ServerRouter conserva l'identità semantica delle qualità invece di affidarsi soltanto agli indici runtime.

CONFIGURAZIONE

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

mods/ServerRouter/config.json

COSA FA

ServerRouter conserva l'identità semantica delle qualità invece di affidarsi soltanto agli indici runtime.

COMPORTAMENTO IMPORTANTE

La diagnostica ItemQuality serve soprattutto quando due server hanno registri o mod differenti.
Se una qualità non è disponibile sulla destinazione, il sistema usa un fallback sicuro e conserva l'identità originale quando possibile.
I log di mapping sono strumenti diagnostici: non sono necessari per una rete stabile.

CAPITOLO 09 · 1 ESEMPI

Placeholder, API e diagnostica

Integra mod companion, ricarica la scoreboard e usa la diagnostica quando serve.

01CONFIGURAZIONE

Placeholder e API per mod companion

La scoreboard include placeholder interni e una API pubblica permette ad altre mod di registrarne di nuovi senza patchare ServerRouter.

CONFIGURAZIONE

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

Java API + scoreboard.json

COSA FA

La scoreboard include placeholder interni e una API pubblica permette ad altre mod di registrarne di nuovi senza patchare ServerRouter.

COMPORTAMENTO IMPORTANTE

I placeholder custom sono case-insensitive e non possono sottrarre i placeholder interni già risolti.
La scoreboard nativa può restare disattivata: i placeholder di ServerRouter possono essere registrati e usati da scoreboard o mod esterne compatibili.
BetterScoreBoard è supportata tramite l'integrazione dedicata. Se utilizzi un'altra scoreboard e i placeholder non vengono riconosciuti, contattaci: possiamo valutare l'aggiunta di una compatibilità specifica.
La Presence/Network API è in sola lettura ed evita che ogni mod debba interrogare separatamente il database.
Per la scoreboard nativa usa /scoreboard reload dopo modifiche a configurazione, logo o layout.

Prima di usare un esempio

Gli esempi sono volutamente concentrati su un modulo alla volta. Integra le proprietà mostrate nel file corrispondente invece di sostituire una configurazione di produzione completa con un esempio parziale.

Le credenziali database e gli host mostrati qui sono esempi. Non pubblicare mai password o segreti reali e usa lo stesso database condiviso soltanto sui server appartenenti alla stessa rete fidata.

La release pubblica usa il posizionamento horizontal/vertical della scoreboard. I vecchi campi offsetRight/offsetTop delle build di sviluppo non fanno parte della configurazione documentata.

TORNA SU