HyTari Studios · Guide officiel de configuration

Server Router

Configurez le réseau en comprenant réellement chaque module.

Une référence pratique pour Server Router - Network Sync. Parcourez les modules depuis l'identité du serveur et les routes jusqu'aux systèmes partagés, au scoreboard natif et à la synchronisation d'inventaire optionnelle. Chaque section associe un JSON copiable à une explication de son comportement.

COMMENCER LE GUIDE PAGE DU MOD

AVANT DE COMMENCER

Bien démarrer

ÉTAPE 01

Installer sur chaque serveur

Utilisez la même build de ServerRouter sur chaque nœud du réseau.

ÉTAPE 02

Configurer un nœud à la fois

Attribuez à chaque serveur un serverId unique, son host/port et le bon rôle.

ÉTAPE 03

Tester avant ouverture

Vérifiez les routes et la protection backend avec des comptes staff avant de les utiliser pour le trafic public.

ServerRouter est une infrastructure réseau : configurez soigneusement identifiants, hosts, permissions et règles d'accès direct. Conservez une sauvegarde de la configuration de production avant de modifier plusieurs modules.

CHAPITRE 01 · 1 EXEMPLES

Installation et rôle

Identifiez le serveur dans le réseau et choisissez router, backend ou les deux.

01CONFIGURATION

Identité et rôle du serveur

Chaque nœud du réseau doit avoir un serverId unique et une adresse accessible par les autres serveurs.

CONFIGURATION

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

mods/ServerRouter/config.json

CE QUE ÇA FAIT

Chaque nœud du réseau doit avoir un serverId unique et une adresse accessible par les autres serveurs.

COMPORTEMENT IMPORTANT

role: main active le routage, backend accepte les transferts et both combine les deux rôles.
serverId doit rester stable et correspondre à la valeur utilisée dans les routes et modules réseau.
acceptingPlayers peut retirer temporairement un serveur des destinations sans l'arrêter.

CHAPITRE 02 · 1 EXEMPLES

Base de données et heartbeat

Configurez MariaDB et la fréquence de publication de l'état de chaque serveur.

01CONFIGURATION

MariaDB, heartbeat et état en ligne

ServerRouter utilise MariaDB pour partager état, présence, transferts et modules réseau.

CONFIGURATION

{
  "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 QUE ÇA FAIT

ServerRouter utilise MariaDB pour partager état, présence, transferts et modules réseau.

COMPORTEMENT IMPORTANT

Tous les serveurs du même réseau doivent pointer vers la même base.
heartbeatIntervalSeconds définit la fréquence de mise à jour du statut.
offlineTimeoutSeconds détermine quand un nœud sans heartbeat est considéré indisponible.

CHAPITRE 03 · 1 EXEMPLES

Routes et commandes

Définissez destinations, commandes, alias, permissions et messages des routes.

01CONFIGURATION

Routes, commandes, alias et permissions

Chaque route relie une commande à un serveur de destination et est vérifiée avant transfert.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Chaque route relie une commande à un serveur de destination et est vérifiée avant transfert.

COMPORTEMENT IMPORTANT

La commande est enregistrée sans slash dans le JSON et utilisée en jeu comme /survival.
aliases ajoute des noms alternatifs au même transfert.
Avant le referral, ServerRouter vérifie état, capacité et disponibilité de la destination.

CHAPITRE 04 · 1 EXEMPLES

Sécurité des transferts

Protégez les backends et gérez autorisations temporaires, rejoin et cooldowns.

01CONFIGURATION

Protection backend et jetons de transfert

Les backends peuvent refuser l'accès direct et n'accepter que les joueurs issus d'un transfert autorisé.

CONFIGURATION

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

mods/ServerRouter/config.json

CE QUE ÇA FAIT

Les backends peuvent refuser l'accès direct et n'accepter que les joueurs issus d'un transfert autorisé.

COMPORTEMENT IMPORTANT

Avec allowDirectAccess=false, le backend utilise l'autorisation temporaire générée par le serveur source.
La whitelist native de Hytale reste l'autorité finale pour l'accès.
Les cooldowns d'arrivée évitent les rebonds de portail juste après connexion ou transfert.

CHAPITRE 05 · 1 EXEMPLES

Portails

Réutilisez les mêmes routes pour générer des portails cohérents avec les contrôles réseau.

01CONFIGURATION

Portails liés aux routes

Les portails utilisent les destinations configurées dans le router et conservent les mêmes contrôles de disponibilité et de sécurité.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Les portails utilisent les destinations configurées dans le router et conservent les mêmes contrôles de disponibilité et de sécurité.

COMPORTEMENT IMPORTANT

Aucune seconde destination n'est nécessaire pour le portail : la route est la source commune.
Les assets des portails sont générés par le plugin et chargés comme runtime asset pack.
Si la destination est hors ligne, pleine ou indisponible, le transfert est bloqué.

CHAPITRE 06 · 1 EXEMPLES

Systèmes partagés

Chat, événements, liste de joueurs et Presence API partagent les informations entre tous les serveurs.

01CONFIGURATION

Chat et événements globaux

Les serveurs peuvent partager chat et événements majeurs afin que Hub, Survival, Dungeon, Creative et les autres nœuds forment un même réseau.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Les serveurs peuvent partager chat et événements majeurs afin que Hub, Survival, Dungeon, Creative et les autres nœuds forment un même réseau.

COMPORTEMENT IMPORTANT

Network Chat relaie les messages entre serveurs participants tout en conservant le nom du serveur source et un format commun configurable.
captureMode choisit la source du chat local ; remoteFormat réutilise le format disponible et fallbackFormat fournit une alternative sûre.
serverDisplayNames attribue un nom lisible à chaque serveur, comme Hub, Survival ou Creative, au lieu du seul serverId technique.
Network Events peut annoncer join, quit et changement de serveur sur tout le réseau, chaque type étant indépendant.
suppressServerSwitchJoinQuit évite qu'un changement de serveur apparaisse comme un faux quit suivi d'un join.
quitDelaySeconds distingue une vraie déconnexion d'un transfert en cours ; respectVanish évite d'exposer les joueurs cachés quand l'intégration le permet.
Network Player List et Presence API partagent la présence avec serveurs et mods compatibles sans requête SQL séparée pour chaque intégration.

CHAPITRE 07 · 2 EXEMPLES

Scoreboard natif

Configurez contenu, position, couleurs, logo et overrides pour mondes ou instances dynamiques.

01CONFIGURATION

Scoreboard global

Le scoreboard natif est indépendant et peut être placé dans l'un des quatre coins avec un offset en pixels.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Le scoreboard natif est indépendant et peut être placé dans l'un des quatre coins avec un offset en pixels.

COMPORTEMENT IMPORTANT

Le scoreboard natif est optionnel : il peut être désactivé sans désactiver ServerRouter ni ses systèmes réseau.
horizontal accepte left:<px> ou right:<px>; vertical accepte top:<px> ou bottom:<px>.
backgroundColor accepte default, none ou une couleur HEX #RRGGBB.
logo: none masque le logo. Les lignes supportent formatage et placeholders dynamiques.
Avec un scoreboard externe, vous pouvez utiliser les placeholders ServerRouter sans afficher celui intégré.

02CONFIGURATION

Overrides par monde et instances dynamiques

Un monde peut hériter de la configuration globale et ne modifier que les champs nécessaires.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Un monde peut hériter de la configuration globale et ne modifier que les champs nécessaires.

COMPORTEMENT IMPORTANT

Le matching est insensible à la casse et supporte * pour les mondes d'instance à suffixe dynamique.
Priorité : nom exact > wildcard le plus spécifique > configuration globale.
Un override peut changer position, lignes, largeur, fond ou logo sans dupliquer tout le bloc global.

CHAPITRE 08 · 2 EXEMPLES

Inventory Sync et ItemQuality

Synchronisez les inventaires en sécurité et préservez ItemQuality entre registries différents.

01CONFIGURATION

Inventory Sync

La synchronisation d'inventaire est optionnelle et utilise des locks temporaires pour protéger chargement, sauvegarde et transferts concurrents.

CONFIGURATION

{
  "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 QUE ÇA FAIT

La synchronisation d'inventaire est optionnelle et utilise des locks temporaires pour protéger chargement, sauvegarde et transferts concurrents.

COMPORTEMENT IMPORTANT

Activez-la uniquement sur les serveurs qui doivent partager le même profil d'inventaire.
Les locks empêchent les accès concurrents pouvant provoquer duplications ou écrasements.
Laissez debugQualityMapping désactivé en utilisation normale.

02CONFIGURATION

ItemQuality entre registries différents

ServerRouter conserve l'identité sémantique des qualités au lieu de dépendre uniquement des index runtime.

CONFIGURATION

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

mods/ServerRouter/config.json

CE QUE ÇA FAIT

ServerRouter conserve l'identité sémantique des qualités au lieu de dépendre uniquement des index runtime.

COMPORTEMENT IMPORTANT

Le diagnostic ItemQuality est surtout utile avec des registries ou mods différents.
Si une qualité manque sur la destination, un fallback sûr est utilisé tout en conservant l'identité d'origine si possible.
Les logs de mapping sont des outils de diagnostic, inutiles sur un réseau stable.

CHAPITRE 09 · 1 EXEMPLES

Placeholders, API et diagnostic

Intégrez les mods compagnons, rechargez le scoreboard et utilisez le diagnostic si nécessaire.

01CONFIGURATION

Placeholders et API pour mods compagnons

Le scoreboard contient des placeholders internes et une API publique permet aux autres mods d'en enregistrer sans patcher ServerRouter.

CONFIGURATION

{
  "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 QUE ÇA FAIT

Le scoreboard contient des placeholders internes et une API publique permet aux autres mods d'en enregistrer sans patcher ServerRouter.

COMPORTEMENT IMPORTANT

Les placeholders custom sont insensibles à la casse et ne peuvent pas remplacer les placeholders internes déjà résolus.
Le scoreboard natif peut rester désactivé : les placeholders ServerRouter peuvent être utilisés par des scoreboards ou mods externes compatibles.
BetterScoreBoard est supporté via l'intégration dédiée. Si un autre scoreboard ne reconnaît pas les placeholders, une compatibilité spécifique peut être étudiée.
La Presence/Network API en lecture seule évite que chaque mod interroge séparément la base.
Pour le scoreboard natif, utilisez /scoreboard reload après changement de configuration, logo ou layout.

Avant d'utiliser un exemple

Les exemples se concentrent volontairement sur un seul module. Fusionnez les propriétés montrées dans le fichier correspondant au lieu de remplacer une configuration complète par un exemple partiel.

Les identifiants de base de données et hosts affichés sont des exemples. Ne publiez jamais de vrais mots de passe ou secrets et ne partagez la même base qu'entre serveurs du même réseau de confiance.

La version publique utilise horizontal/vertical pour la position du scoreboard. Les anciens champs offsetRight/offsetTop des builds de développement ne font pas partie de la configuration documentée.

RETOUR EN HAUT