Partie 2 - Edgegap : Hébergement et orchestration de serveurs de jeu

La première chose dont votre projet a besoin, ce sont les packages Unity Gaming Services et les trois services sur lesquels repose cette intégration : Authentication, Matchmaker et Cloud Code. Si vous les exécutez déjà dans votre projet, vous pouvez passer à la partie suivante.

Commencez dans l'éditeur Unity et installez les deux packages dont vous avez besoin :

1. Sélectionnez « Window », puis « Package Manager ».

2. Définissez la source des packages sur « Unity Registry ».

3. Recherchez « Cloud Code », sélectionnez-le, puis sélectionnez « Install ».

4. Recherchez « Multiplayer Services » et sélectionnez « Install ». Ce package regroupe le Matchmaker et importe Authentication pour vous.

Après quelques secondes, les deux apparaissent dans votre projet.

Ensuite, activez les services dans le tableau de bord Unity Cloud. Tout d'abord, assurez-vous que votre projet est lié à un projet Unity Cloud : sous « Edit », « Project Settings », « Services », vous devriez voir un projet lié et son identifiant. S'il n'est pas encore lié, liez-le ici. Si vous rencontrez des problèmes à cette étape, le flux d'assistance d'Unity est l'endroit idéal pour les résoudre.

Ensuite, dans votre navigateur, accédez à votre projet sur cloud.unity.com et connectez-vous. Activez les trois services : Authentication, Matchmaker et Cloud Code.

Prenez note de votre environnement, qui est « production » par défaut. Tout ce que vous configurez à partir d'ici, votre secret, votre module et votre file d'attente, doit résider dans ce même environnement, alors restez cohérent.

Nous reviendrons plus tard pour la file d'attente du Matchmaker, une fois que la pièce dont elle dépend existera.

Partie 3 - L'allocateur Edgegap

Le cœur de cette intégration est un petit module Cloud Code qui permet au Matchmaker d'Unity de déployer un serveur sur Edgegap. Il est distribué officiellement par Unity, vous n'avez donc qu'à le configurer et le déployer.

Lorsqu'une partie se forme, ce module effectue deux tâches. Tout d'abord, il demande à Edgegap de déployer un serveur pour votre application. Ensuite, il interroge ce déploiement jusqu'à ce que le serveur soit prêt, et transmet son adresse et son port au Matchmaker, qui les transmet à vos joueurs.

Le module réside dans le répertoire des hébergeurs de Matchmaker d'Unity, distinct de votre projet de jeu. Ouvrez un terminal et clonez-le à côté de votre projet. La commande de clonage est la même sur tous les systèmes d'exploitation ; seul le chemin du dossier diffère :

macOS / Linux

mkdir -p ~/unity-ugs-hosting
cd ~/unity-ugs-hosting
git

mkdir -p ~/unity-ugs-hosting
cd ~/unity-ugs-hosting
git

mkdir -p ~/unity-ugs-hosting
cd ~/unity-ugs-hosting
git

Windows (PowerShell)

mkdir ~\unity-ugs-hosting
cd ~\unity-ugs-hosting
git clone https://github.com/Unity-Technologies/matchmaker-hosting-providers.git

mkdir ~\unity-ugs-hosting
cd ~\unity-ugs-hosting
git clone https://github.com/Unity-Technologies/matchmaker-hosting-providers.git

mkdir ~\unity-ugs-hosting
cd ~\unity-ugs-hosting
git clone https://github.com/Unity-Technologies/matchmaker-hosting-providers.git

Ouvrez le dossier cloné et accédez à l'allocateur Edgegap. Le seul fichier que vous configurez est l'allocateur lui-même ; il contient quelques constantes vers le haut, marquées par un « TODO », qui lui indiquent quelle application Edgegap déployer.

Définissez le nom de l'application pour qu'il corresponde exactement à votre application Edgegap telle qu'elle apparaît dans votre tableau de bord, par exemple com-unity-multiplayer-samples-coop. Un seul caractère erroné ici provoquera un échec silencieux plus tard, alors copiez-le plutôt que de le retaper.

Définissez le nom de la version sur le nom exact de la version de votre application sur la plateforme Edgegap.

Le nom du port devrait déjà être gameport, ce qui correspond au port sur notre version. Notez que ce port est UDP sur 7777 pour cet exemple. Cela peut être différent avec d'autres netcodes. Par conséquent, veillez à consulter la documentation de votre netcode pour connaître le port exact correspondant à votre cas d'utilisation.

Laissez le nom du secret comme EDGEGAP_API_TOKEN ; nous allons créer ce secret ensuite. Enregistrez le fichier.

Cloud Code lit votre jeton API Edgegap à partir d'un secret, de sorte que le module ne contient jamais votre clé. Depuis votre tableau de bord Edgegap, sélectionnez votre organisation, puis « Tokens », et copiez votre jeton. Ensuite, dans le tableau de bord Unity Cloud, accédez aux secrets de votre projet sous le menu « Administration », et ajoutez un secret :

• Clé : EDGEGAP_API_TOKEN (tout en majuscules)

• Valeur : votre jeton API Edgegap, et uniquement le jeton, sans mots ni espaces supplémentaires

• Environnement : le même que tout le reste (par exemple, production)

Déployez maintenant le module depuis l'éditeur. De retour dans Unity, créez une « Cloud Code C# Module Reference » dans le dossier principal de votre projet. Sélectionnez-la et, dans l'Inspecteur, pointez-la vers le fichier de solution de l'allocateur, le fichier .sln situé dans le répertoire que vous venez de cloner.

C'est l'étape qui pose souvent problème : si la référence pointe vers autre chose que le vrai fichier de solution, le déploiement semblera avoir fonctionné mais enverra un modèle vide à la place. Assurez-vous donc qu'il s'agit bien du véritable fichier .sln.

Ouvrez la fenêtre « Deployment » sous « Services ». Votre module y apparaît. Assurez-vous qu'il est coché et défini sur votre environnement, puis sélectionnez « Deploy Selected ». Il compile, compresse et publie. Cela utilise le SDK .NET, version 8 ou ultérieure ; vous pouvez confirmer votre version avec :

dotnet --version

dotnet --version

dotnet --version

Maintenant la partie importante : vérifiez que le déploiement a réussi, au lieu de faire confiance au message de réussite. De retour dans le tableau de bord Unity Cloud, ouvrez votre module Cloud Code et vérifiez ses points de terminaison. Vous devriez en voir deux, le point de terminaison d'allocation (allocate) et le point de terminaison d'interrogation (poll), chacun renvoyant le type de réponse propre à l'allocateur. Si vous voyez ces deux-là, votre module est actif. Si un type de retour indique simplement « string » à la place, la référence du module pointait vers le mauvais fichier, alors revenez en arrière et corrigez-le avant de continuer.

Partie 4 - Configuration de la file d'attente

Une fois le module actif, vous pouvez indiquer au Matchmaker de l'utiliser. C'est ici que votre matchmaker existant est orienté vers Edgegap, et pour la plupart des projets, c'est le seul véritable changement.

Dans la section Matchmaker, créez une file d'attente, par exemple bossroom-queue. Pour ce test simple, autorisez deux joueurs par ticket.

Dans la file d'attente, créez un pool et définissez son type d'hébergement sur « Hosting via Cloud Code ». C'est l'interrupteur qui envoie l'allocation à votre module plutôt qu'ailleurs. Pointez le pool vers votre module : l'allocateur, son point de terminaison d'allocation et son point de terminaison d'interrogation. Le délai d'expiration de l'allocation correspond au temps pendant lequel le Matchmaker attend qu'Edgegap lance un serveur ; la valeur par défaut est largement suffisante, car un nouveau déploiement peut prendre un peu de temps.

Enfin, définissez les règles de match. Pour le match le plus simple possible, une équipe de deux joueurs : une équipe, un nombre d'équipes de un, et un nombre de joueurs avec un minimum et un maximum de deux. Laissez le remplissage automatique (backfill) désactivé et n'ajoutez pas d'autres règles pour le moment ; vous pourrez adapter tout cela à votre jeu plus tard.

Enregistrez, et votre file d'attente devient active. Voilà pour le backend, et votre matchmaker se déploie désormais sur Edgegap.

Partie 5 - Le client de Matchmaking

Vos joueurs ont besoin d'un moyen de demander un match, et de quelque chose qui récupère le serveur attribué et les y connecte. Dans notre fork, ce client existe déjà, nous allons donc voir ce qu'il fait et comment obtenir l'équivalent dans votre propre jeu.

En résumé : le client connecte un joueur, crée un ticket de matchmaking dans votre file d'attente et attend tout en interrogeant pour un résultat. Dès que le Matchmaker attribue un serveur, il lit l'adresse et le port de ce serveur et les transmet à l'appel de connexion propre au jeu.

Cet appel de connexion est la seule partie spécifique à votre netcode. Dans Boss Room, il s'agit de StartClientIp. Dans votre jeu, c'est tout ce que votre projet utilise déjà pour connecter un client à un serveur par adresse et port. Tout le reste, la création du ticket, l'attente et la lecture de l'attribution, est identique pour tout projet Unity Gaming Services.

Si votre projet ne dispose pas encore de ce client, vous pouvez donner l'invite ci-dessous à n'importe quel assistant de codage IA. Il commence par analyser votre projet pour trouver comment votre jeu se connecte à un serveur, puis génère un petit client de matchmaking autonome qui crée un ticket, attend l'attribution et appelle votre propre méthode de connexion, quel que soit le netcode que vous utilisez. Il ajoute également quelques commodités de test que notre exemple garde simples : il donne à chaque instance locale une identité de joueur unique afin que vous puissiez tester deux clients sur une seule machine, et il effectue des interrogations avec un intervalle plus long. Comme toujours, la ligne de connexion dépend de votre jeu, examinez donc ce qu'elle produit.

Add Unity Gaming Services (UGS) Matchmaker support to my game as a temporary,
self-contained client for testing dedicated-server allocation. Do NOT modify my
existing netcode; only add a new component that drives matchmaking and then calls
my existing connect path.

First, audit (read-only) and tell me before writing code:
  1) The method my project calls to connect a client to a server by IP/address and
     port — file, line, exact signature, and the TYPE of the port parameter.
  2) The transport in use and where connection data is ultimately set.
State these findings, then proceed.

Then create one MonoBehaviour that:
  - Initializes UGS (UnityServices.InitializeAsync) and signs in anonymously via
    Authentication.
  - For same-machine testing, sets a UNIQUE profile per running instance BEFORE
    sign-in (e.g. a value derived from the project path or a random id); if a player
    is already signed in, sign out first, then switch profile, then sign in — so two
    local instances get distinct player IDs.
  - Creates a UGS ticket on a serialized queue-name field (default it to my queue),
    with one player entry using the signed-in player id.
  - Polls the ticket status no more often than every 3 seconds, and treats a failed
    poll as retryable (catch and continue the loop, do not abort) until an assignment
    arrives or a timeout elapses.
  - On assignment, reads the assigned IP and port and passes them into the connect
    method identified in the audit, converting the port to the exact type that method
    expects.
  - Exposes a simple temporary on-screen "Matchmake" button to trigger it.

Keep it minimal and commented. Tell me the audit findings first, then show the full
component. Do not change any other files

Add Unity Gaming Services (UGS) Matchmaker support to my game as a temporary,
self-contained client for testing dedicated-server allocation. Do NOT modify my
existing netcode; only add a new component that drives matchmaking and then calls
my existing connect path.

First, audit (read-only) and tell me before writing code:
  1) The method my project calls to connect a client to a server by IP/address and
     port — file, line, exact signature, and the TYPE of the port parameter.
  2) The transport in use and where connection data is ultimately set.
State these findings, then proceed.

Then create one MonoBehaviour that:
  - Initializes UGS (UnityServices.InitializeAsync) and signs in anonymously via
    Authentication.
  - For same-machine testing, sets a UNIQUE profile per running instance BEFORE
    sign-in (e.g. a value derived from the project path or a random id); if a player
    is already signed in, sign out first, then switch profile, then sign in — so two
    local instances get distinct player IDs.
  - Creates a UGS ticket on a serialized queue-name field (default it to my queue),
    with one player entry using the signed-in player id.
  - Polls the ticket status no more often than every 3 seconds, and treats a failed
    poll as retryable (catch and continue the loop, do not abort) until an assignment
    arrives or a timeout elapses.
  - On assignment, reads the assigned IP and port and passes them into the connect
    method identified in the audit, converting the port to the exact type that method
    expects.
  - Exposes a simple temporary on-screen "Matchmake" button to trigger it.

Keep it minimal and commented. Tell me the audit findings first, then show the full
component. Do not change any other files

Add Unity Gaming Services (UGS) Matchmaker support to my game as a temporary,
self-contained client for testing dedicated-server allocation. Do NOT modify my
existing netcode; only add a new component that drives matchmaking and then calls
my existing connect path.

First, audit (read-only) and tell me before writing code:
  1) The method my project calls to connect a client to a server by IP/address and
     port — file, line, exact signature, and the TYPE of the port parameter.
  2) The transport in use and where connection data is ultimately set.
State these findings, then proceed.

Then create one MonoBehaviour that:
  - Initializes UGS (UnityServices.InitializeAsync) and signs in anonymously via
    Authentication.
  - For same-machine testing, sets a UNIQUE profile per running instance BEFORE
    sign-in (e.g. a value derived from the project path or a random id); if a player
    is already signed in, sign out first, then switch profile, then sign in — so two
    local instances get distinct player IDs.
  - Creates a UGS ticket on a serialized queue-name field (default it to my queue),
    with one player entry using the signed-in player id.
  - Polls the ticket status no more often than every 3 seconds, and treats a failed
    poll as retryable (catch and continue the loop, do not abort) until an assignment
    arrives or a timeout elapses.
  - On assignment, reads the assigned IP and port and passes them into the connect
    method identified in the audit, converting the port to the exact type that method
    expects.
  - Exposes a simple temporary on-screen "Matchmake" button to trigger it.

Keep it minimal and commented. Tell me the audit findings first, then show the full
component. Do not change any other files

Enfin, connectez le client à la scène, le seul changement de scène dont le fork a besoin. Dans votre scène de départ, dans notre cas le menu principal, créez un objet de jeu vide : depuis la Hiérarchie, faites un clic droit, « Create Empty », et nommez-le « Matchmaker ». Une fois sélectionné, ajoutez le composant « Edgegap Matchmaker Client ».

Un champ est important ici : le nom de la file d'attente (queue name). Définissez-le sur le nom exact de la file d'attente que vous avez créée, par exemple bossroom-queue. S'il ne correspond pas à votre file d'attente, les tickets n'iront nulle part, alors double-vérifiez-le. Enregistrez la scène.