HyTari Studios · Offizielle Konfigurationsanleitung

Server Router

Konfiguriere das Netzwerk, indem du jedes Modul verstehst.

Eine praktische Referenz für Server Router - Network Sync. Folge den Modulen von Serveridentität und Routen über gemeinsame Systeme bis zur nativen Scoreboard und optionalen Inventarsynchronisierung. Jeder Abschnitt kombiniert kopierbares JSON mit einer Erklärung der tatsächlichen Wirkung.

ANLEITUNG STARTEN MOD-SEITE

BEVOR DU BEGINNST

Erste Schritte

SCHRITT 01

Auf jedem Server installieren

Verwende auf jedem Netzwerkknoten denselben ServerRouter-Build.

SCHRITT 02

Einen Knoten nach dem anderen konfigurieren

Gib jedem Server eine eindeutige serverId, eigenen Host/Port und die richtige Rolle.

SCHRITT 03

Vor Freigabe testen

Prüfe Routen und Backend-Schutz mit Staff-Konten, bevor öffentlicher Traffic darauf angewiesen ist.

ServerRouter ist Netzwerkinfrastruktur: Zugangsdaten, Hostnamen, Berechtigungen und Direct-Access-Regeln bewusst konfigurieren. Vor Änderungen an mehreren Modulen ein Backup der Produktionskonfiguration behalten.

KAPITEL 01 · 1 BEISPIELE

Installation und Rolle

Identifiziere den Server im Netzwerk und lege fest, ob er Router, Backend oder beides ist.

01KONFIGURATION

Serveridentität und Rolle

Jeder Netzwerkknoten benötigt eine eindeutige serverId und eine von den anderen Servern erreichbare Adresse.

KONFIGURATION

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

mods/ServerRouter/config.json

WAS ES MACHT

Jeder Netzwerkknoten benötigt eine eindeutige serverId und eine von den anderen Servern erreichbare Adresse.

WICHTIGES VERHALTEN

role: main aktiviert Routingfunktionen, backend akzeptiert Transfers, both kombiniert beide Rollen.
serverId muss stabil bleiben und mit dem Wert in Routen und Netzwerkmodulen übereinstimmen.
acceptingPlayers kann einen Server vorübergehend aus den verfügbaren Zielen entfernen, ohne ihn abzuschalten.

KAPITEL 02 · 1 BEISPIELE

Datenbank und Heartbeat

Konfiguriere MariaDB und wie oft jeder Server seinen Status veröffentlicht.

01KONFIGURATION

MariaDB, Heartbeat und Online-Status

ServerRouter nutzt MariaDB, um Status, Präsenz, Transfers und Netzwerkmodule zu teilen.

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

WAS ES MACHT

ServerRouter nutzt MariaDB, um Status, Präsenz, Transfers und Netzwerkmodule zu teilen.

WICHTIGES VERHALTEN

Alle Server desselben Netzwerks müssen dieselbe Datenbank verwenden.
heartbeatIntervalSeconds legt fest, wie oft der Knoten seinen Status aktualisiert.
offlineTimeoutSeconds bestimmt, wann ein Knoten ohne Heartbeat als nicht verfügbar gilt.

KAPITEL 03 · 1 BEISPIELE

Routen und Befehle

Definiere Ziele, Befehle, Aliase, Berechtigungen und Routenmeldungen.

01KONFIGURATION

Routen, Befehle, Aliase und Berechtigungen

Jede Route verbindet einen Befehl mit einem Zielserver und wird vor dem Transfer geprüft.

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

WAS ES MACHT

Jede Route verbindet einen Befehl mit einem Zielserver und wird vor dem Transfer geprüft.

WICHTIGES VERHALTEN

Der Befehl steht im JSON ohne Slash und wird im Spiel als /survival verwendet.
aliases fügt alternative Namen für denselben Transfer hinzu.
Vor dem Referral prüft ServerRouter Status, Kapazität und Verfügbarkeit des Zielservers.

KAPITEL 04 · 1 BEISPIELE

Transfersicherheit

Schütze Backends und steuere temporäre Autorisierungen, Rejoin und Cooldowns.

01KONFIGURATION

Backend-Schutz und Transfer-Tokens

Backend-Server können Direktzugriffe ablehnen und nur Spieler aus autorisierten Transfers akzeptieren.

KONFIGURATION

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

mods/ServerRouter/config.json

WAS ES MACHT

Backend-Server können Direktzugriffe ablehnen und nur Spieler aus autorisierten Transfers akzeptieren.

WICHTIGES VERHALTEN

Bei allowDirectAccess=false nutzt das Backend die temporäre Autorisierung des Quellservers.
Hytales native Whitelist bleibt die letzte Instanz für den Serverzugriff.
Arrival-Cooldowns verhindern versehentliches Portal-Bouncing direkt nach Login oder Transfer.

KAPITEL 05 · 1 BEISPIELE

Portale

Nutze dieselben Routen für Reiseportale mit denselben Netzwerkprüfungen.

01KONFIGURATION

Mit Routen verbundene Portale

Portale nutzen die im Router konfigurierten Ziele und dieselben Verfügbarkeits- und Sicherheitsprüfungen.

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

WAS ES MACHT

Portale nutzen die im Router konfigurierten Ziele und dieselben Verfügbarkeits- und Sicherheitsprüfungen.

WICHTIGES VERHALTEN

Für das Portal ist kein zweites Ziel nötig: Die Route ist die gemeinsame Quelle.
Portal-Assets werden vom Plugin erzeugt und als Runtime Asset Pack geladen.
Ist das Ziel offline, voll oder nicht verfügbar, wird der Transfer blockiert.

KAPITEL 06 · 1 BEISPIELE

Gemeinsame Systeme

Chat, Events, Player List und Presence API teilen Informationen zwischen allen Servern.

01KONFIGURATION

Globaler Chat und Events

Server können Chat und wichtige Netzwerkereignisse teilen, sodass Hub, Survival, Dungeon, Creative und weitere Knoten wie ein gemeinsames Netzwerk wirken.

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

WAS ES MACHT

Server können Chat und wichtige Netzwerkereignisse teilen, sodass Hub, Survival, Dungeon, Creative und weitere Knoten wie ein gemeinsames Netzwerk wirken.

WICHTIGES VERHALTEN

Network Chat leitet Spielernachrichten zwischen teilnehmenden Servern weiter und behält Quellserver sowie ein konfigurierbares gemeinsames Format.
captureMode bestimmt die Quelle des lokalen Chats; remoteFormat nutzt vorhandene Formatierung, fallbackFormat liefert eine sichere Alternative.
serverDisplayNames gibt jedem Server einen lesbaren Namen wie Hub, Survival oder Creative statt nur der technischen serverId.
Network Events kann Join, Quit und Serverwechsel netzwerkweit melden; jeder Ereignistyp ist separat schaltbar.
suppressServerSwitchJoinQuit verhindert, dass ein Serverwechsel als falsches Quit plus neues Join erscheint.
quitDelaySeconds hilft echte Disconnects von laufenden Transfers zu unterscheiden; respectVanish schützt versteckte Spieler, wenn die Integration dies unterstützt.
Network Player List und Presence API teilen Präsenzdaten mit kompatiblen Servern und Mods, ohne dass jede Integration separat die Datenbank abfragen muss.

KAPITEL 07 · 2 BEISPIELE

Native Scoreboard

Konfiguriere Inhalt, Position, Farben, Logo und Overrides für Welten oder dynamische Instanzen.

01KONFIGURATION

Globale Scoreboard

Die native Scoreboard ist unabhängig und kann mit Pixel-Offsets in einer der vier Ecken positioniert werden.

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

WAS ES MACHT

Die native Scoreboard ist unabhängig und kann mit Pixel-Offsets in einer der vier Ecken positioniert werden.

WICHTIGES VERHALTEN

Die native Scoreboard ist optional und kann abgeschaltet werden, ohne ServerRouter oder seine Netzwerksysteme zu deaktivieren.
horizontal akzeptiert left:<px> oder right:<px>; vertical akzeptiert top:<px> oder bottom:<px>.
backgroundColor akzeptiert default, none oder eine HEX-Farbe #RRGGBB.
logo: none blendet das Logo aus. Zeilen unterstützen Formatierung und dynamische Placeholder.
Bei externer Scoreboard können ServerRouter-Placeholder genutzt werden, ohne die native Scoreboard anzuzeigen.

02KONFIGURATION

Overrides pro Welt und dynamische Instanzen

Eine Welt kann die globale Konfiguration erben und nur benötigte Felder überschreiben.

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

WAS ES MACHT

Eine Welt kann die globale Konfiguration erben und nur benötigte Felder überschreiben.

WICHTIGES VERHALTEN

Das Matching ist case-insensitive und unterstützt * für Instanzwelten mit dynamischem Suffix.
Priorität: exakter Weltname > spezifischster Wildcard-Treffer > globale Konfiguration.
Ein Override kann Position, Zeilen, Breite, Hintergrund oder Logo ändern, ohne den gesamten globalen Block zu duplizieren.

KAPITEL 08 · 2 BEISPIELE

Inventory Sync und ItemQuality

Synchronisiere Inventare sicher und erhalte ItemQuality über unterschiedliche Registries hinweg.

01KONFIGURATION

Inventory Sync

Die Inventarsynchronisierung ist optional und verwendet temporäre Locks für Laden, Speichern und konkurrierende 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

WAS ES MACHT

Die Inventarsynchronisierung ist optional und verwendet temporäre Locks für Laden, Speichern und konkurrierende Transfers.

WICHTIGES VERHALTEN

Nur auf Servern aktivieren, die dasselbe Inventarprofil teilen sollen.
Locks verhindern parallele Zugriffe, die Duplikationen oder Überschreibungen verursachen könnten.
debugQualityMapping im normalen Betrieb deaktiviert lassen.

02KONFIGURATION

ItemQuality bei unterschiedlichen Registries

ServerRouter bewahrt die semantische Identität von Qualitäten, statt nur Runtime-Indizes zu verwenden.

KONFIGURATION

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

mods/ServerRouter/config.json

WAS ES MACHT

ServerRouter bewahrt die semantische Identität von Qualitäten, statt nur Runtime-Indizes zu verwenden.

WICHTIGES VERHALTEN

ItemQuality-Diagnose ist vor allem bei unterschiedlichen Registries oder Mods nützlich.
Ist eine Qualität am Ziel nicht verfügbar, nutzt das System einen sicheren Fallback und bewahrt die ursprüngliche Identität, wenn möglich.
Mapping-Logs sind Diagnosewerkzeuge und für ein stabiles Netzwerk nicht erforderlich.

KAPITEL 09 · 1 BEISPIELE

Placeholder, API und Diagnose

Integriere Companion-Mods, lade die Scoreboard neu und nutze Diagnose bei Bedarf.

01KONFIGURATION

Placeholder und API für Companion-Mods

Die Scoreboard enthält interne Placeholder; über eine öffentliche API können andere Mods neue registrieren, ohne ServerRouter zu patchen.

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

WAS ES MACHT

Die Scoreboard enthält interne Placeholder; über eine öffentliche API können andere Mods neue registrieren, ohne ServerRouter zu patchen.

WICHTIGES VERHALTEN

Custom Placeholder sind case-insensitive und können bereits aufgelöste interne Placeholder nicht übernehmen.
Die native Scoreboard kann deaktiviert bleiben; ServerRouter-Placeholder lassen sich in kompatiblen externen Scoreboards oder Mods verwenden.
BetterScoreBoard wird über die dedizierte Integration unterstützt. Erkennt eine andere Scoreboard die Placeholder nicht, kann eine spezifische Kompatibilität geprüft werden.
Die schreibgeschützte Presence/Network API verhindert separate Datenbankabfragen jeder Mod.
Für die native Scoreboard nach Änderungen an Konfiguration, Logo oder Layout /scoreboard reload verwenden.

Vor der Verwendung eines Beispiels

Die Beispiele konzentrieren sich absichtlich auf jeweils ein Modul. Füge die gezeigten Eigenschaften in die passende Datei ein, statt eine vollständige Produktionskonfiguration durch ein Teilbeispiel zu ersetzen.

Die gezeigten Datenbank-Zugangsdaten und Hostnamen sind Beispiele. Veröffentliche niemals echte Passwörter oder Secrets und nutze dieselbe gemeinsame Datenbank nur für Server desselben vertrauenswürdigen Netzwerks.

Die öffentliche Release verwendet horizontal/vertical für die Scoreboard-Position. Die alten offsetRight/offsetTop-Felder aus Entwicklungsbuilds gehören nicht zur dokumentierten Konfiguration.

NACH OBEN