Configurer et gérer un serveur dédié Hytale

La sortie d’Hytale en accès anticipé s’accompagne d’outils serveur complets pour les administrateurs et les joueurs souhaitant héberger leurs propres mondes. Ce guide détaille l’installation, la configuration et l’exploitation d’un serveur Hytale dédié, des prérequis système aux architectures multi-serveurs avancées.

Le serveur Hytale fonctionne sur n’importe quel appareil disposant d’au moins 4 Go de mémoire et de Java 25, avec une prise en charge native des architectures x64 et arm64. Contrairement aux solutions serveur traditionnelles, Hytale utilise le protocole QUIC sur UDP plutôt que TCP, ce qui nécessite une configuration réseau spécifique. Le système d’authentification OAuth2 obligatoire permet de communiquer avec les API de service tout en limitant les abus.

La consommation de ressources dépend fortement du comportement des joueurs. Le nombre d’entités (PNJ, mobs) sollicite principalement le processeur, tandis que la mémoire vive augmente avec la surface de monde chargée. Une surveillance active des performances permet d’ajuster les paramètres selon le style de jeu et le nombre de joueurs connectés.

Prérequis et installation de Java 25

Le serveur nécessite Java 25 pour fonctionner. Adoptium propose une distribution recommandée par Hypixel Studios, téléchargeable depuis leur site officiel. L’installation varie selon le système d’exploitation mais reste standard pour les environnements Java.

Une fois installé, la vérification s’effectue via terminal avec la commande java --version. Le retour attendu affiche OpenJDK 25.0.1 avec les détails de l’environnement d’exécution Temurin. Cette étape confirme que le système reconnaît correctement la version requise avant de poursuivre.

Obtention des fichiers serveur

Deux méthodes permettent de récupérer les fichiers nécessaires au serveur. La copie manuelle depuis l’installation du launcher convient pour des tests rapides, tandis que l’outil Hytale Downloader CLI facilite les déploiements en production et les mises à jour régulières.

Copie manuelle depuis le launcher

Les fichiers se trouvent dans le dossier d’installation du launcher, dont l’emplacement varie selon le système. Sous Windows, le chemin est %appdata%\Hytale\install\release\package\game\latest. Les utilisateurs Linux consultent $XDG_DATA_HOME/Hytale/install/release/package/game/latest, et macOS utilise ~/Application Support/Hytale/install/release/package/game/latest.

Le répertoire contient deux dossiers (Client et Server) et un fichier Assets.zip d’environ 3 Go. Seuls le dossier Server et Assets.zip sont nécessaires pour faire fonctionner un serveur dédié. Cette méthode présente l’inconvénient de nécessiter une copie manuelle à chaque mise à jour du jeu.

Hytale Downloader CLI

Cet outil en ligne de commande télécharge automatiquement les fichiers serveur et assets avec authentification OAuth2. Disponible pour Linux et Windows dans une archive nommée hytale-downloader.zip, il simplifie la gestion des versions en production.

Les commandes principales incluent ./hytale-downloader pour télécharger la dernière version stable, -print-version pour afficher le numéro de version sans télécharger, et -patchline pre-release pour accéder aux versions de prévisualisation. L’option -check-update vérifie les mises à jour du téléchargeur lui-même, tandis que -skip-update-check désactive cette vérification automatique.

Le paramètre -download-path permet de spécifier un fichier de destination personnalisé, utile pour les scripts automatisés ou les configurations particulières. Le fichier QUICKSTART.md inclus dans l’archive détaille l’utilisation complète de l’outil.

Démarrage et authentification du serveur

Le lancement du serveur s’effectue avec la commande java -jar HytaleServer.jar --assets PathToAssets.zip, en remplaçant PathToAssets.zip par le chemin réel vers le fichier d’assets. Au premier démarrage, le serveur demande une authentification via le système OAuth2.

La commande /auth login device dans la console serveur génère un code d’autorisation temporaire et une URL. L’administrateur visite https://accounts.hytale.com/device, saisit le code fourni (format ABCD-1234), et autorise le serveur depuis son compte Hytale. Le délai d’expiration du code est de 900 secondes (15 minutes).

Une fois l’autorisation validée depuis le navigateur, le serveur confirme la connexion avec le message « Authentication successful! Mode: OAUTH_DEVICE ». Le serveur peut alors accepter les connexions des joueurs. Cette authentification reste active et ne nécessite pas de renouvellement à chaque redémarrage.

Limites d’authentification

Hypixel Studios impose une limite de 100 serveurs par licence de jeu pour prévenir les abus pendant la période d’accès anticipé. Les administrateurs nécessitant plus de capacité doivent acquérir des licences supplémentaires ou demander un compte Fournisseur de Serveur (Server Provider).

Les fournisseurs d’hébergement ou les opérateurs de réseaux multi-serveurs doivent consulter le guide Server Provider Authentication pour l’authentification automatique et dynamique de grandes quantités de serveurs. Ce processus diffère de l’authentification device standard et offre une gestion centralisée.

Configuration réseau et pare-feu

Hytale utilise exclusivement le protocole QUIC sur UDP, contrairement à la plupart des jeux multijoueurs qui emploient TCP. Cette différence nécessite des configurations réseau spécifiques pour assurer la connectivité des joueurs.

Port par défaut et personnalisation

Le port par défaut est 5520. Pour utiliser un port différent, l’argument --bind modifie l’adresse d’écoute : java -jar HytaleServer.jar --assets PathToAssets.zip --bind 0.0.0.0:25565. Le format attend une adresse IP (0.0.0.0 pour toutes les interfaces) suivie du port souhaité.

Redirection de ports

Les serveurs hébergés derrière un routeur nécessitent une redirection de port UDP (pas TCP) vers la machine serveur. La configuration s’effectue dans l’interface d’administration du routeur, en spécifiant le port externe (5520 ou personnalisé) vers l’IP locale du serveur avec le protocole UDP.

Règles de pare-feu

Sous Windows, PowerShell permet d’autoriser le trafic entrant avec : New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action Allow. Le nom d’affichage est personnalisable et facilite l’identification dans le pare-feu Windows Defender.

Les systèmes Linux avec iptables utilisent sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPT. Pour les distributions avec ufw, la commande simplifiée est sudo ufw allow 5520/udp. Ces règles doivent être rendues persistantes selon la méthode de votre distribution.

Considérations NAT

QUIC gère bien la traversée NAT dans la majorité des cas. Les configurations NAT symétriques peuvent causer des problèmes de connexion, auquel cas un VPS ou un serveur dédié avec IP publique résout le souci. Les joueurs derrière un NAT de grade opérateur (fréquent sur les réseaux mobiles) se connectent normalement en tant que clients.

Commandes et arguments disponibles

La commande java -jar HytaleServer.jar --help affiche l’ensemble des arguments acceptés par le serveur. Les options principales couvrent l’authentification, la configuration réseau, les sauvegardes automatiques et le chargement de plugins.

L’argument --auth-mode bascule entre les modes authenticated (par défaut) et offline. Le mode offline désactive l’authentification et convient uniquement aux tests locaux, jamais pour un serveur public. L’option --allow-op autorise l’attribution des permissions d’opérateur.

Les sauvegardes automatiques s’activent avec --backup, tandis que --backup-dir spécifie le répertoire de destination et --backup-frequency définit l’intervalle en minutes (30 par défaut). Cette fonctionnalité protège contre la perte de données sans intervention manuelle.

Le paramètre --accept-early-plugins reconnaît que le chargement de plugins early peut causer des problèmes de stabilité. Cette option doit être activée explicitement pour confirmer la compréhension des risques associés.

Structure des fichiers serveur

Le répertoire serveur s’organise en plusieurs dossiers et fichiers de configuration. Le dossier .cache/ stocke les fichiers optimisés générés par le serveur, logs/ contient les journaux d’événements, et mods/ héberge les modifications installées.

Le répertoire universe/ centralise toutes les données de mondes et de joueurs. Chaque monde possède son propre sous-dossier dans universe/worlds/ avec un fichier config.json dédié. Cette séparation permet de gérer plusieurs mondes indépendants sur un même serveur.

Fichiers de configuration racine

Le fichier config.json définit les paramètres généraux du serveur. permissions.json gère le système de permissions, whitelist.json liste les joueurs autorisés en mode liste blanche, et bans.json répertorie les joueurs bannis avec les raisons et durées.

Ces fichiers JSON sont lus au démarrage et écrits lors d’actions en jeu (attribution de permissions, bannissements via commandes). Les modifications manuelles pendant que le serveur tourne risquent d’être écrasées. Pour les changements persistants, il faut arrêter le serveur, éditer les fichiers, puis redémarrer.

Configuration des mondes

Chaque monde dispose d’un config.json détaillé contrôlant des aspects comme la génération de terrain, le stockage des chunks, les règles de gameplay et les systèmes de ticking. Les paramètres incluent l’activation du PvP (IsPvpEnabled), les dégâts de chute (IsFallDamageEnabled), et le gel du temps de jeu (IsGameTimePaused).

Les options de sauvegarde se configurent individuellement : IsSavingPlayers pour les données joueurs, IsSavingChunks pour les morceaux de terrain, et IsUnloadingChunks pour le déchargement des zones inactives. La désactivation du déchargement augmente la consommation mémoire mais améliore les performances dans certains scénarios.

Le paramètre RequiredPlugins spécifie les plugins obligatoires pour accéder au monde, garantissant que tous les joueurs disposent des fonctionnalités nécessaires. Chaque monde s’exécute sur son propre thread principal et délègue le travail parallèle à un pool de threads partagé.

Installation et gestion des mods

Les mods Hytale s’installent simplement en plaçant les fichiers .zip ou .jar dans le dossier mods/. Les sources comme CurseForge proposent des modifications créées par la communauté. Le serveur charge automatiquement les mods présents au démarrage.

Pour les serveurs en développement actif de plugins, la désactivation du système de rapport de crash Sentry évite de soumettre des erreurs de développement aux serveurs d’Hypixel Studios. L’argument --disable-sentry désactive cette télémétrie : java -jar HytaleServer.jar --assets PathToAssets.zip --disable-sentry.

Cette option ne doit pas rester active sur les serveurs de production, car les rapports de crash aident l’équipe de développement à identifier et corriger les bugs affectant les serveurs publics.

Optimisation des performances

Le serveur Hytale inclut plusieurs mécanismes d’optimisation des performances, de la compilation ahead-of-time aux plugins de gestion de ressources.

Cache AOT (Ahead-Of-Time)

Le serveur est livré avec un cache AOT pré-entraîné (HytaleServer.aot) qui améliore les temps de démarrage en évitant la phase de warmup JIT. Cette fonctionnalité repose sur JEP-514 introduit dans les versions récentes de Java.

L’activation s’effectue avec l’argument JVM -XX:AOTCache=HytaleServer.aot avant le jar : java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets PathToAssets.zip. Les gains de performance varient selon le matériel mais réduisent significativement le temps avant que le serveur soit pleinement opérationnel.

Distance de vue et consommation mémoire

La distance de vue (view distance) constitue le principal facteur de consommation RAM. Hypixel Studios recommande de limiter la distance maximale à 12 chunks (384 blocs) pour équilibrer performances et expérience de jeu.

À titre de comparaison, les serveurs Minecraft utilisent par défaut 10 chunks (160 blocs). La valeur par défaut d’Hytale (384 blocs) équivaut approximativement à 24 chunks Minecraft. Sans ajustement, la consommation mémoire dépasse celle d’un serveur Minecraft standard. L’adaptation de ce paramètre selon le nombre de joueurs attendu optimise l’utilisation des ressources.

Plugins recommandés

Les partenaires de développement Nitrado et Apex Hosting maintiennent des plugins pour les besoins d’hébergement courants. Nitrado:WebServer fournit une base pour les applications web et API, tandis que Nitrado:Query expose le statut du serveur (nombre de joueurs, etc.) via HTTP.

Le plugin Nitrado:PerformanceSaver ajuste dynamiquement la distance de vue selon l’utilisation des ressources, réduisant automatiquement la charge lors des pics d’activité. ApexHosting:PrometheusExporter expose des métriques détaillées du serveur et de la JVM pour une surveillance approfondie via Prometheus et Grafana.

Arguments JVM et configuration avancée

Les paramètres de la machine virtuelle Java influencent directement les performances et la stabilité du serveur. Les arguments -Xms et -Xmx contrôlent respectivement la taille initiale et maximale du tas (heap).

L’allocation mémoire optimale dépend du style de jeu et du nombre de joueurs. Sans outils spécialisés, déterminer la consommation réelle d’un processus Java reste difficile. L’expérimentation avec différentes valeurs de -Xmx permet de trouver l’équilibre entre performance et utilisation mémoire.

Un symptôme typique de pression mémoire est l’augmentation de l’utilisation CPU due au ramasse-miettes (garbage collection). Si le serveur dispose d’une limite mémoire trop basse, le GC s’active fréquemment pour libérer de l’espace, impactant les performances globales.

Le guide JVM Parameters de Baeldung détaille les paramètres importants comme les stratégies de garbage collection, les options de compilation et le tuning de performance. Ces réglages avancés conviennent aux administrateurs expérimentés souhaitant extraire les meilleures performances de leur infrastructure.

Architecture multi-serveurs

Hytale propose des mécanismes natifs pour router les joueurs entre serveurs sans proxy inverse comme BungeeCord. Trois systèmes complémentaires permettent de construire des architectures complexes : le transfert de joueurs (referral), la redirection à la connexion et le fallback de déconnexion.

Transfert de joueurs (Player Referral)

Cette méthode transfère un joueur connecté vers un autre serveur. Le serveur source envoie un paquet contenant l’hôte cible, le port et une charge utile optionnelle de 4 Ko maximum. Le client ouvre une nouvelle connexion vers la destination et présente cette charge lors du handshake.

La méthode Java est PlayerRef.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data). La charge utile transite par le client et peut donc être altérée. Pour sécuriser les transferts, les données doivent être signées cryptographiquement (HMAC avec un secret partagé par exemple) afin que le serveur récepteur vérifie l’authenticité.

Les cas d’usage incluent le transfert entre serveurs de jeu, la transmission de contexte de session et le contrôle d’accès via un système de matchmaking. Une fonctionnalité à venir permettra de spécifier plusieurs destinations tentées séquentiellement pour gérer les serveurs indisponibles.

Redirection à la connexion

Pendant le handshake de connexion, un serveur peut rejeter le joueur et le rediriger vers une autre adresse. Le client se connecte automatiquement à la nouvelle destination sans interaction supplémentaire.

L’événement PlayerSetupConnectEvent.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data) intercepte la connexion initiale. Cette approche convient pour la répartition de charge, le routage géographique et l’application d’un passage obligatoire par un lobby avant d’accéder aux serveurs de jeu.

Déconnexion avec fallback

Lorsqu’un joueur est déconnecté inopinément (crash serveur, interruption réseau), le client se reconnecte automatiquement à un serveur fallback préconfiguré plutôt que de retourner au menu principal.

Cette fonction maintient l’engagement du joueur en le redirigeant vers un lobby après un crash de serveur de jeu ou pendant les redémarrages de maintenance. L’implémentation des paquets fallback devrait arriver quelques semaines après le lancement de l’accès anticipé selon la documentation officielle.

Construction d’un proxy personnalisé

Les serveurs proxy personnalisés se construisent avec Netty QUIC, la bibliothèque réseau utilisée par Hytale. Les définitions de paquets et la structure du protocole sont disponibles dans HytaleServer.jar sous le package com.hypixel.hytale.protocol.packets.

Ces classes permettent de décoder, inspecter, modifier ou transférer le trafic entre clients et serveurs backend. Les proxies personnalisés ouvrent des possibilités comme l’analyse de trafic, les systèmes anti-triche côté proxy, ou la gestion centralisée des connexions pour de grands réseaux.

Gestion du protocole et compatibilité

Le protocole Hytale utilise un hash pour vérifier la compatibilité entre client et serveur. Si les hashs ne correspondent pas exactement, la connexion est rejetée. Cette limitation actuelle impose que client et serveur utilisent précisément la même version protocolaire.

Lors de la sortie d’une mise à jour, les serveurs doivent se mettre à jour immédiatement sous peine de perdre la connexion avec les joueurs ayant installé la nouvelle version client. Cette contrainte temporaire devrait être levée prochainement.

Une tolérance de protocole permettant une différence de ±2 versions entre client et serveur est prévue. Les opérateurs disposeront alors d’une fenêtre de mise à jour sans perdre la connectivité avec les joueurs, facilitant les maintenances et réduisant les interruptions de service.

Artéfact Maven Central

Le fichier HytaleServer.jar sera publié sur Maven Central pour servir de dépendance dans les projets de modding. Cette publication permettra aux développeurs d’importer facilement les classes et API serveur dans leurs environnements de développement.

La configuration Maven utilisera le groupId com.hypixel.hytale et l’artifactId Server. Les détails précis concernant le versioning et les dépendances transitives seront finalisés pour le lancement. Les ressources communautaires de modding fourniront les informations actualisées sur l’utilisation de ces dépendances.

Fonctionnalités futures prévues

Plusieurs systèmes importants sont en développement ou en évaluation pour enrichir l’écosystème serveur d’Hytale.

Découverte de serveurs et minijeux

Un catalogue de découverte accessible depuis le menu principal permettra aux joueurs de parcourir les serveurs et minijeux. Les opérateurs pourront inscrire leurs serveurs pour promouvoir leur contenu directement auprès des joueurs.

Les conditions d’inscription incluent le respect des directives pour opérateurs de serveur et des standards communautaires. Les opérateurs doivent évaluer précisément le contenu de leur serveur, ces notes alimentant les filtres et contrôles parentaux. Les violations de l’auto-évaluation déclarée entraînent des actions d’application selon les politiques d’opérateur.

Les nombres de joueurs affichés proviendront de la télémétrie client plutôt que des déclarations serveur, empêchant la falsification des comptes. Les joueurs pourront ainsi se fier aux chiffres présentés lors de la navigation. Les serveurs pourront néanmoins afficher un compte non vérifié aux utilisateurs les ayant ajoutés en dehors du système de découverte.

Système de groupes (Parties)

Un système de groupes permettra aux joueurs de se regrouper et de rester ensemble lors des transferts serveur et files d’attente de minijeux. L’intégration avec la découverte de serveurs laissera les groupes parcourir les serveurs et rejoindre ensemble.

Les exigences et restrictions de taille de groupe seront visibles avant de rejoindre, informant les groupes de leur compatibilité avec le serveur choisi. Ce système pose les bases d’une expérience sociale fluide où les amis naviguent dans l’écosystème Hytale sans coordination manuelle.

Système de paiement intégré

Une passerelle de paiement intégrée au client permettra aux serveurs d’accepter des paiements sans gérer les détails bancaires ni construire d’infrastructure. Optionnelle mais encouragée, cette solution bénéficie aux opérateurs en traitant les transactions via un système sécurisé et traçable.

Les joueurs profitent d’une expérience sans visite de sites externes, toutes les transactions restant dans l’écosystème Hytale. Les informations de paiement ne quittent pas l’environnement sécurisé de la plateforme.

Support des enregistrements SRV

Les enregistrements SRV DNS permettraient aux joueurs de se connecter avec un nom de domaine (play.exemple.com) sans spécifier de port, le DNS résolvant l’adresse et le port réels.

Cette fonctionnalité n’est actuellement pas prise en charge et reste en évaluation. L’absence de bibliothèque C# éprouvée pour la résolution SRV constitue le blocage principal. Les options existantes nécessitent soit un client DNS complet (complexité excessive, risques de stabilité), soit manquent de maturité pour un composant réseau critique.

L’équipe évalue les alternatives et reconsidérera cette fonction lorsqu’une solution appropriée émergera. Les administrateurs peuvent utiliser des redirections à la connexion pour offrir une expérience similaire en attendant.

Points d’API officiels

Les serveurs authentifiés accéderont à des points d’API officiels pour les données joueurs, le versioning et les opérations serveur. Ces endpoints réduisent la dépendance aux services tiers en fournissant des données autoritaires directement depuis Hytale.

Les endpoints planifiés incluent la résolution UUID ↔ nom de joueur (requêtes individuelles et en masse), la version du jeu (version actuelle, version du protocole, vérification des mises à jour), et les profils joueurs (données de profil, cosmétiques, rendus d’avatar, informations publiques).

La télémétrie serveur permettra de signaler le statut, le nombre de joueurs et les métadonnées pour l’intégration à la découverte. Les systèmes de signalement traiteront les violations des conditions d’utilisation, et l’intégration paiement gérera les transactions via la passerelle intégrée.

Endpoints en considération

Les sanctions globales permettraient de vérifier si un joueur fait l’objet de sanctions au niveau plateforme (distinct des bans serveur spécifiques). La liste d’amis récupérerait les contacts d’un joueur (avec permissions appropriées) pour les fonctionnalités sociales.

Les abonnements webhook notifieraient les serveurs d’événements comme les changements de nom de joueur ou les mises à jour de sanctions. Ces notifications push éliminent le besoin de polling régulier.

Les objectifs de conception incluent des limites de débit généreuses avec endpoints en masse et réponses optimisées pour la mise en cache. L’accès authentifié obligatoire prévient les abus, et l’API versionnée garantit des contrats stables avec fenêtres de dépréciation pour les changements cassants.