HyTari Studios · Officiële configuratiehandleiding

Server Router

Configureer het netwerk door elk onderdeel echt te begrijpen.

Een praktische referentie voor Server Router - Network Sync. Volg de onderdelen van serveridentiteit en routes tot gedeelde systemen, de native scoreboard en optionele inventarissynchronisatie. Elke sectie combineert kopieerbare JSON met uitleg over het werkelijke gedrag.

START DE HANDLEIDING MODPAGINA

VOORDAT JE BEGINT

Aan de slag

STAP 01

Installeer op elke server

Gebruik dezelfde ServerRouter-build op elk knooppunt dat aan het netwerk deelneemt.

STAP 02

Configureer één knooppunt tegelijk

Geef elke server een unieke serverId, eigen host/port en de juiste rol.

STAP 03

Test vóór openbare toegang

Controleer routes en backendbescherming met staffaccounts voordat publiek verkeer erop vertrouwt.

ServerRouter is netwerkinfrastructuur: configureer inloggegevens, hosts, rechten en direct-accessregels bewust. Bewaar een back-up van de productieconfiguratie voordat je meerdere modules tegelijk wijzigt.

HOOFDSTUK 01 · 1 VOORBEELDEN

Installatie en rol

Identificeer de server in het netwerk en bepaal of hij router, backend of beide is.

01CONFIGURATIE

Serveridentiteit en rol

Elk netwerkknooppunt heeft een unieke serverId en een door andere servers bereikbaar adres nodig.

CONFIGURATIE

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

mods/ServerRouter/config.json

WAT HET DOET

Elk netwerkknooppunt heeft een unieke serverId en een door andere servers bereikbaar adres nodig.

BELANGRIJK GEDRAG

role: main activeert routing, backend accepteert transfers en both combineert beide rollen.
serverId moet stabiel blijven en gelijk zijn aan de waarde in routes en netwerkmodules.
acceptingPlayers kan een server tijdelijk uit bestemmingen halen zonder hem uit te schakelen.

HOOFDSTUK 02 · 1 VOORBEELDEN

Database en heartbeat

Configureer MariaDB en hoe vaak elke server zijn status publiceert.

01CONFIGURATIE

MariaDB, heartbeat en online-status

ServerRouter gebruikt MariaDB voor gedeelde status, presence, transfers en netwerkmodules.

CONFIGURATIE

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

WAT HET DOET

ServerRouter gebruikt MariaDB voor gedeelde status, presence, transfers en netwerkmodules.

BELANGRIJK GEDRAG

Alle servers in hetzelfde netwerk moeten dezelfde database gebruiken.
heartbeatIntervalSeconds bepaalt hoe vaak de node zijn status bijwerkt.
offlineTimeoutSeconds bepaalt wanneer een node zonder heartbeat niet beschikbaar wordt beschouwd.

HOOFDSTUK 03 · 1 VOORBEELDEN

Routes en commando's

Definieer bestemmingen, commando's, aliassen, rechten en routemeldingen.

01CONFIGURATIE

Routes, commando's, aliassen en rechten

Elke route koppelt een commando aan een bestemmingsserver en wordt vóór transfer gecontroleerd.

CONFIGURATIE

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

mods/ServerRouter/config.json → routes[]

WAT HET DOET

Elke route koppelt een commando aan een bestemmingsserver en wordt vóór transfer gecontroleerd.

BELANGRIJK GEDRAG

Het commando staat zonder slash in JSON en wordt in-game gebruikt als /survival.
aliases voegt alternatieve namen voor dezelfde transfer toe.
Voor referral controleert ServerRouter status, capaciteit en beschikbaarheid van de bestemming.

HOOFDSTUK 04 · 1 VOORBEELDEN

Transferbeveiliging

Bescherm backends en beheer tijdelijke autorisaties, rejoin en cooldowns.

01CONFIGURATIE

Backendbescherming en transfertokens

Backends kunnen directe toegang weigeren en alleen spelers uit geautoriseerde transfers accepteren.

CONFIGURATIE

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

mods/ServerRouter/config.json

WAT HET DOET

Backends kunnen directe toegang weigeren en alleen spelers uit geautoriseerde transfers accepteren.

BELANGRIJK GEDRAG

Met allowDirectAccess=false gebruikt de backend de tijdelijke autorisatie van de bronserver.
Hytales native whitelist blijft de uiteindelijke autoriteit voor toegang.
Arrival-cooldowns voorkomen onbedoeld portal-bouncen direct na login of transfer.

HOOFDSTUK 05 · 1 VOORBEELDEN

Portalen

Gebruik dezelfde routes om reisportalen te genereren met dezelfde netwerkcontroles.

01CONFIGURATIE

Portalen gekoppeld aan routes

Portalen gebruiken de bestemmingen uit de router en behouden dezelfde beschikbaarheids- en veiligheidscontroles.

CONFIGURATIE

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

WAT HET DOET

Portalen gebruiken de bestemmingen uit de router en behouden dezelfde beschikbaarheids- en veiligheidscontroles.

BELANGRIJK GEDRAG

Een tweede bestemming is niet nodig: de route is de gemeenschappelijke bron.
Portal-assets worden door de plugin gegenereerd en als runtime asset pack geladen.
Is de bestemming offline, vol of niet beschikbaar, dan wordt de transfer geblokkeerd.

HOOFDSTUK 06 · 1 VOORBEELDEN

Gedeelde systemen

Chat, events, player list en Presence API delen informatie tussen alle servers.

01CONFIGURATIE

Globale chat en events

Servers kunnen chat en belangrijke netwerkgebeurtenissen delen zodat Hub, Survival, Dungeon, Creative en andere nodes als één netwerk aanvoelen.

CONFIGURATIE

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

WAT HET DOET

Servers kunnen chat en belangrijke netwerkgebeurtenissen delen zodat Hub, Survival, Dungeon, Creative en andere nodes als één netwerk aanvoelen.

BELANGRIJK GEDRAG

Network Chat stuurt berichten door tussen deelnemende servers en behoudt de bronserver plus een configureerbaar gemeenschappelijk formaat.
captureMode bepaalt waar lokale chat vandaan komt; remoteFormat gebruikt bestaande opmaak en fallbackFormat biedt een veilige fallback.
serverDisplayNames geeft leesbare namen zoals Hub, Survival of Creative in plaats van alleen de technische serverId.
Network Events kan join, quit en serverwissel netwerkbreed melden; elk type is afzonderlijk instelbaar.
suppressServerSwitchJoinQuit voorkomt dat een serverwissel als een valse quit plus join verschijnt.
quitDelaySeconds helpt een echte disconnect van een lopende transfer te onderscheiden; respectVanish voorkomt het tonen van verborgen spelers wanneer ondersteund.
Network Player List en Presence API delen aanwezigheid met compatibele servers en mods zonder aparte databasequery per integratie.

HOOFDSTUK 07 · 2 VOORBEELDEN

Native scoreboard

Configureer inhoud, positie, kleuren, logo en overrides voor werelden of dynamische instances.

01CONFIGURATIE

Globale scoreboard

De native scoreboard is onafhankelijk en kan in elk van de vier hoeken met pixel-offsets worden geplaatst.

CONFIGURATIE

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

WAT HET DOET

De native scoreboard is onafhankelijk en kan in elk van de vier hoeken met pixel-offsets worden geplaatst.

BELANGRIJK GEDRAG

De native scoreboard is optioneel en kan uit zonder ServerRouter of netwerksystemen uit te schakelen.
horizontal accepteert left:<px> of right:<px>; vertical accepteert top:<px> of bottom:<px>.
backgroundColor accepteert default, none of een HEX-kleur #RRGGBB.
logo: none verbergt het logo. Regels ondersteunen opmaak en dynamische placeholders.
Met een externe scoreboard kun je ServerRouter-placeholders gebruiken zonder de native scoreboard te tonen.

02CONFIGURATIE

Overrides per wereld en dynamische instances

Een wereld kan globale configuratie erven en alleen noodzakelijke velden overschrijven.

CONFIGURATIE

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

WAT HET DOET

Een wereld kan globale configuratie erven en alleen noodzakelijke velden overschrijven.

BELANGRIJK GEDRAG

Matching is hoofdletterongevoelig en ondersteunt * voor instancewerelden met dynamische suffixen.
Prioriteit: exacte wereldnaam > meest specifieke wildcard > globale configuratie.
Een override kan positie, regels, breedte, achtergrond of logo wijzigen zonder het hele globale blok te dupliceren.

HOOFDSTUK 08 · 2 VOORBEELDEN

Inventory Sync en ItemQuality

Synchroniseer inventarissen veilig en behoud ItemQuality tussen verschillende registries.

01CONFIGURATIE

Inventory Sync

Inventarissynchronisatie is optioneel en gebruikt tijdelijke locks voor laden, opslaan en concurrerende transfers.

CONFIGURATIE

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

WAT HET DOET

Inventarissynchronisatie is optioneel en gebruikt tijdelijke locks voor laden, opslaan en concurrerende transfers.

BELANGRIJK GEDRAG

Activeer alleen op servers die hetzelfde inventarisprofiel moeten delen.
Locks voorkomen gelijktijdige toegang die duplicatie of overschrijving kan veroorzaken.
Laat debugQualityMapping bij normaal gebruik uitgeschakeld.

02CONFIGURATIE

ItemQuality tussen verschillende registries

ServerRouter bewaart de semantische identiteit van kwaliteiten in plaats van alleen runtime-indexen te gebruiken.

CONFIGURATIE

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

mods/ServerRouter/config.json

WAT HET DOET

ServerRouter bewaart de semantische identiteit van kwaliteiten in plaats van alleen runtime-indexen te gebruiken.

BELANGRIJK GEDRAG

ItemQuality-diagnostiek is vooral nuttig bij verschillende registries of mods.
Als een kwaliteit op de bestemming ontbreekt, gebruikt het systeem een veilige fallback en bewaart de oorspronkelijke identiteit waar mogelijk.
Mappinglogs zijn diagnostisch en niet nodig voor een stabiel netwerk.

HOOFDSTUK 09 · 1 VOORBEELDEN

Placeholders, API en diagnostiek

Integreer companion mods, herlaad de scoreboard en gebruik diagnostiek wanneer nodig.

01CONFIGURATIE

Placeholders en API voor companion mods

De scoreboard bevat interne placeholders en een publieke API laat andere mods nieuwe registreren zonder ServerRouter te patchen.

CONFIGURATIE

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

Java API + scoreboard.json

WAT HET DOET

De scoreboard bevat interne placeholders en een publieke API laat andere mods nieuwe registreren zonder ServerRouter te patchen.

BELANGRIJK GEDRAG

Custom placeholders zijn hoofdletterongevoelig en kunnen reeds opgeloste interne placeholders niet overnemen.
De native scoreboard kan uit blijven; ServerRouter-placeholders kunnen in compatibele externe scoreboards of mods worden gebruikt.
BetterScoreBoard wordt ondersteund via de speciale integratie. Herkent een andere scoreboard de placeholders niet, dan kan specifieke compatibiliteit worden bekeken.
De read-only Presence/Network API voorkomt dat elke mod de database apart bevraagt.
Gebruik voor de native scoreboard /scoreboard reload na wijzigingen aan configuratie, logo of layout.

Voordat je een voorbeeld gebruikt

De voorbeelden focussen bewust op één module tegelijk. Voeg de getoonde eigenschappen samen in het juiste bestand in plaats van een volledige productieconfiguratie te vervangen door een deelvoorbeeld.

Databasegegevens en hosts zijn voorbeelden. Publiceer nooit echte wachtwoorden of secrets en gebruik dezelfde gedeelde database alleen voor servers binnen hetzelfde vertrouwde netwerk.

De publieke release gebruikt horizontal/vertical voor scoreboardpositionering. Oude offsetRight/offsetTop-velden uit ontwikkelbuilds horen niet bij de gedocumenteerde configuratie.

NAAR BOVEN