Comment ajouter des salons en ligne (comme sur un serveur de jeu dédié) à n'importe quel jeu multijoueur Unity avec le SDK Server Browser d'Edgegap
Nous allons couvrir chaque étape pour ajouter un système de lobby multijoueur à la demande à votre jeu Unity à l'aide du SDK Server Browser d'Edgegap, où les joueurs sont automatiquement connectés à un serveur dédié à la demande. Cette approche fonctionne avec n'importe quel netcode. Commençons !
Cette intégration s'appuie sur notre tutoriel de serveur dédié. Elle suppose que vous avez déjà un projet Unity configuré pour les serveurs dédiés et que vous savez comment concevoir, conteneuriser et uploader un serveur sur Edgegap. Si ce n'est pas le cas, suivez d'abord ce tutoriel.
Partie 1 - Installer le SDK Server Browser
Le plugin Edgegap du tutoriel de serveur du00e9diu00e9 gu00e8re la construction et le du00e9ploiement de votre serveur de jeu. Le Navigateur de Serveurs est un package distinct.
Dans Unity, depuis la barre de navigation supu00e9rieure, su00e9lectionnez u00abu00a0Windowu00a0u00bb, puis u00abu00a0Package Managementu00a0u00bb, et enfin u00abu00a0Package Manageru00a0u00bb. Su00e9lectionnez l'icu00f4ne u00abu00a0plusu00a0u00bb, puis u00abu00a0Add package from git URLu00a0u00bb. Collez l'URL de l'SDK.
https://github.com/edgegap/edgegap-unity-sdk.git
Une fois tu00e9lu00e9chargu00e9, trouvez l'onglet u00abu00a0Samplesu00a0u00bb dans le volet de du00e9tails de l'SDK et importez l'exemple u00abu00a0Server Browser - Auto-Assignu00a0u00bb. Cela ajoute deux scripts u00e0 votre projet : un gestionnaire de serveur et un gestionnaire de client. Le gestionnaire de client ru00e9serve une place sur le serveur de jeu et transmet l'adresse du serveur u00e0 votre jeu pour s'y connecter. Le gestionnaire de serveur enregistre votre serveur de jeu aupru00e8s du Navigateur de Serveurs lors de son du00e9marrage et signale la capacitu00e9 en joueurs disponible. Les deux sont intu00e9gru00e9s dans la scu00e8ne lors d'une u00e9tape ultu00e9rieure.
L'SDK s'occupe de presque tout pour vous. Ce qu'il vous reste u00e0 faire, c'est d'ajouter les parties spu00e9cifiques au netcode : les lignes de code qui connectent votre jeu au serveur attribuu00e9, un court protocole d'accueil (handshake) qui indique au serveur quels joueurs rejoignent, et la libu00e9ration qui libu00e8re leur place lorsqu'ils quittent.
Avertissement
Assurez-vous d'ajouter le plugin Unity d'Edgegap en utilisant "Ajouter un projet à partir de Git" pour vous assurer d'utiliser la dernière version du projet.
Sélectionnez "Fenêtre" puis "Gestionnaire de paquets"
Cliquez sur l'icône "+", puis sélectionnez "Ajouter un projet depuis Git"
Collez l'URL du plugin Unity d'Edgegap : "https://github.com/edgegap/edgegap-unity-plugin.git"
Sélectionnez "Installer"
Partie 2 - Générer le code d'intégration
L'intégration utilise des invites universelles que tout assistant de codage IA peut exécuter dans n'importe quel projet Unity. Les invites couvrent deux étapes : la première consiste à faire auditer votre projet par l'assistant pour comprendre comment il se connecte et comment il envoie des messages, et la seconde consiste à écrire l'intégration sur la base de cet audit. Les deux invites sont disponibles dans les commentaires de la vidéo pour être copiées. L'exemple à l'écran utilise l'échantillon Billiards de Mirror Networking, mais les invites sont indépendantes du code réseau utilisé.
La première invite est en lecture seule et ne modifie rien. Elle demande à l'assistant de trouver et de signaler quelques éléments : comment votre client se connecte à un serveur à l'aide d'une adresse et d'un port personnalisés, comment votre code réseau envoie de petits messages personnalisés du client au serveur, comment il signale qu'un client s'est connecté, et comment il signale sur le serveur qu'un joueur s'est déconnecté afin qu'une place puisse être restituée au pool. Pour l'échantillon Mirror, l'audit confirme que le client se connecte en appelant StartClient sur le NetworkManager de Mirror, avec l'adresse et le port configurés sur le transport actif, et identifie comment Mirror envoie un message réseau et déclenche son événement de connexion de client.
La seconde invite permet à l'assistant d'effectuer la modification sur la base de cet audit. Elle réalise trois actions. Premièrement, elle crée un petit script de connecteur autonome qui, sur le serveur, écoute l'identifiant de chaque joueur et confirme leur réservation, et sur le client, envoie cet identifiant une fois connecté. Deuxièmement, elle adapte le gestionnaire de client de la liste des serveurs pour se connecter au serveur en utilisant l'adresse et le port renvoyés par la liste des serveurs, démarrant ainsi le client via votre code réseau. Troisièmement, elle libère la place du joueur lorsqu'il se déconnecte, afin que le serveur libère de l'espace pour de nouveaux joueurs au lieu de se remplir au fil du temps.
La même approche fonctionne pour d'autres codes réseau : l'audit s'adapte au projet que vous utilisez, et la modification applique les changements en conséquence.
Un détail spécifique au code réseau mérite d'être souligné, car l'audit le détecte pour vous. Dans Mirror, l'événement de connexion de client est réinitialisé au démarrage du client, le connecteur s'y abonne donc après le démarrage du client, et non avant. L'audit met cela en évidence et la modification gère cette situation.
Partie 3 - Ajouter les scripts à la scène
Le code existe, mais dans Unity, un script ne fait rien tant qu'il n'est pas attaché à un objet de jeu.
Tout d'abord, créez un objet de jeu vide et nommez-le « Test-Connector ». Ajoutez le script de connecteur généré par l'assistant. Ensuite, créez un autre objet vide pour le gestionnaire de serveur et ajoutez le composant « Server Browser Server Handler », en laissant ses champs vides pour le moment. Ajoutez ensuite un autre objet de jeu vide, nommez-le « Server Browser Client Handler », ajoutez le script du même nom et laissez également les champs de son composant vides. Ces champs seront renseignés avec les détails de la plateforme à l'étape suivante.
Partie 4 - Créer une liste de serveurs
Sur la plateforme Edgegap, ouvrez la section « Server Browser » et créez-en un nouveau. Donnez-lui un nom pour votre propre référence, tel que « quickstart », et choisissez la configuration « Simple Example ». Démarrez la liste de serveurs et laissez-lui un instant pour se mettre en ligne. Avec l'offre gratuite, la liste s'arrête automatiquement après quelques heures, ce qui convient parfaitement pour les tests.
Une fois en ligne, examinez ses détails. Vous verrez une URL d'API et deux jetons distincts : un jeton de serveur et un jeton de client. Les trois sont nécessaires, et les deux jetons ont des rôles différents, veillez donc à ne pas les confondre.
De retour dans Unity, ajoutez ces informations aux deux gestionnaires. Sur le gestionnaire de serveur, collez l'URL de l'API et le jeton de serveur. Sur le gestionnaire de client, collez la même URL de l'API et le jeton de client. Utilisez le jeton approprié pour chaque gestionnaire, car une inversion accidentelle créera des erreurs de connexion. Enfin, sauvegardez la scène.
Le jeton de serveur ne réside jamais que sur le serveur headless exécuté sur Edgegap, jamais sur la machine d'un joueur. Le coller directement dans le composant simplifie ce tutoriel, mais dans une architecture de production, vous le définiriez comme une variable d'environnement dans la version de votre application, ce qui remplace la valeur de l'inspecteur et maintient votre jeton hors des fichiers de votre projet.
Partie 5 - Compiler et déployer le serveur
Une nouvelle version de l'application est requise. Cette étape est facile à omettre mais essentielle : le gestionnaire de serveur lit les informations d'URL et de jeton à partir des champs du composant que vous venez de remplir, et les serveurs de jeu précédemment téléchargés ne disposent pas de ces informations. La compilation et le téléchargement du serveur sont donc obligatoires.
Ouvrez le module d'hébergement d'Edgegap, puis compilez, conteneurisez et téléchargez votre serveur exactement de la même manière que dans le tutoriel du serveur dédié, soit individuellement, soit en utilisant le bouton « build from source », qui exécute toutes ces étapes en une seule fois.
Une fois le serveur téléchargé, créez une politique de mise à l'échelle sur la liste de serveurs (Server Browser). Nommez-la « on-demand », définissez le nombre d'instances actives minimales (« Minimum Active Instances ») sur un, associez-la à l'application et à la version que vous venez de télécharger, et laissez l'option « Private Hosts » vide afin qu'elle soit déployée sur le cloud. C'est ce minimum d'une instance active qui maintient un unique serveur actif et prêt à tout moment — il s'agit de votre salon à la demande. Enregistrez la politique comme active, et en moins d'une minute, elle déploie automatiquement le serveur sur le réseau d'Edgegap. Dans les journaux de déploiement, vous devriez voir le serveur s'enregistrer, signaler un état sain, et indiquer qu'il est découvrable avec ses places disponibles. Votre salon multijoueur à la demande est désormais en ligne.
Partie 6 - Test
Pour tester avec deux joueurs, utilisez le Multiplayer Play Mode d'Unity, qui est abordé dans le tutoriel sur le serveur dédié. Lors de la lecture, chaque joueur contacte le Server Browser, réserve une place, reçoit l'adresse du serveur et se connecte automatiquement — aucun d'eux n'a à saisir d'adresse. Du côté du serveur, chaque joueur est confirmé et une place est d'ores et déjà réservée. Les deux joueurs sont placés dans le même serveur cloud, et les actions de chaque joueur sont reproduites dans la scène de jeu de l'autre.
Remarque pour la production : un serveur fraîchement attribué peut être encore en cours de démarrage pendant un court instant ; vous devriez donc ajouter une fonction de tentative de connexion successive qui vérifie la connexion à quelques reprises, à quelques secondes d'intervalle, afin de pallier ce délai. Ce tutoriel se déploie sur le réseau cloud d'Edgegap comme un moyen simple de tester en développement ; si vous préférez un déploiement vers des solutions de type flotte (fleet) pendant le développement, veuillez consulter la documentation.
Partie 7 - Prochaines étapes
Le exemple simple utilisé ici est un point de départ. À partir de là, vous pouvez faire évoluer votre intégration de Server Browser dans plusieurs directions.
Notre documentation couvre des fonctionnalités supplémentaires, telles que la possibilité de rechercher et de parcourir les serveurs par paramètres, notamment la région, la capacité ou le mode de jeu, afin que les joueurs puissent choisir un serveur spécifique plutôt que d'être assignés automatiquement. Vous pouvez également épingler votre serveur à un parc réservé ou à un parc privé (Private Fleet) au lieu du cloud en ajoutant des identifiants d'hôte à la politique de mise à l'échelle (scaling policy).
Vous pouvez également rejoindre notre communauté sur Discord pour demander de l'aide à notre équipe de développement et à d'autres studios pour adapter le Server Browser à votre jeu.
Analyse approfondie du code : qu'ajouter et pourquoi
Cette analyse approfondie facultative couvre le code réel, pour ceux qui souhaitent comprendre l'intégration. Les modifications sont spécifiques à l'exemple Mirror, mais l'idée est universelle pour tout netcode : prenez l'adresse et le port que le Server Browser vous donne, transmettez-les à votre système réseau et connectez-vous — puis indiquez au serveur quels joueurs viennent de se connecter afin qu'il confirme la réservation.
La première étape est le flux de connexion. Une fois que le client communique avec le serveur, le Server Browser doit toujours savoir que les joueurs sont effectivement arrivés afin de confirmer leur réservation de place et de maintenir son décompte de places exact. C'est la deuxième étape : une fois connecté, le client envoie son identifiant de joueur au serveur, et le serveur le signale au Server Browser.
Le connecteur définit un petit message réseau qui transporte l'identifiant du joueur — le même identifiant que le client a utilisé pour réserver sa place. Du côté du client, une fois connecté, il envoie cet identifiant au serveur. Il y a un détail de Mirror qui mérite d'être répété ici : il s'abonne à l'événement connecté après le démarrage du client, car Mirror réinitialise cet événement au démarrage du client.
Dans le gestionnaire du client, l'identifiant du joueur est généré à la volée lors de l'exécution, de sorte que chaque joueur — y compris ceux simulés — obtient un identifiant unique.
Le cœur de l'intégration est la réponse à la réservation de place. Lorsque le Server Browser réserve une place, il renvoie l'adresse et le port du serveur. Vous configurez ces éléments sur le NetworkManager de Mirror et son transport, démarrez le client, puis vous vous abonnez à l'événement de connexion pour pouvoir envoyer l'identifiant. Le port est lu sur le transport actif d'une manière neutre vis-à-vis du netcode, de sorte que la même logique s'applique à d'autres netcodes — seuls l'adresse exacte, le transport et l'appel de démarrage du client sont spécifiques à Mirror.
Une dernière remarque pour la production : au lieu de coller le jeton (token) du serveur directement dans le composant, vous pouvez le définir comme variables d'environnement dans la version de votre application — SB_BASE_URL et SB_SERVER_TOKEN — qui remplacent les valeurs du composant, afin que votre jeton ne figure jamais dans les fichiers de votre projet.
C'est tout pour le Server Browser d'Edgegap, qui permet aux développeurs de jeux d'exécuter des serveurs dédiés persistants et d'en attribuer automatiquement l'accès aux joueurs, avec seulement une petite quantité de code, dans un système de type lobby.
