Comment intégrer le matchmaking à votre jeu multijoueur Unity Engine

-> Cet article est basé sur la documentation de Matchmaking. Si vous rencontrez des problèmes ou des divergences, veuillez vous référer au guide original, car ils sont plus fréquemment mis à jour.

L'exemple suivant vous aidera à tester le flux de joueurs de base de matchmaking pour un jeu multijoueur Unity Engine, à savoir :

• Créer l'instance de matchmaker sur le cluster d'hébergement partagé,

• Définir les règles et paramètres dans votre configuration de matchmaker,

• Et enfin, tester le flux de joueurs et gérer les tickets de joueurs avec notre API.

Il existe cinq étapes pour implémenter notre matchmaker dans votre jeu :

1. La première étape consiste à créer un compte et à utiliser notre exemple de jeu simple. Voilà, vous avez (techniquement) déjà fait la moitié du chemin ! Vous devrez seulement intégrer le matchmaker dans votre jeu (voir étape 5).

2. Maintenant, vous ne devriez jamais suivre aveuglément un exemple JSON que vous avez trouvé sur Internet, et il est donc fortement recommandé d'adapter les règles ci-dessus à votre jeu au tour par tour. L'étape 2 (« Explorer la configuration ») est notre « comment lire » qui explore la fonction de chaque fonction de règles de matchmaking (« Explorer la configuration »).

3. L'étape 3 (« Revoir les détails de l'instance ») couvre votre matchmaker personnel et spécifique afin de s'assurer qu'il est déployé et fonctionne avec la conception de votre jeu.

4. L'étape 4, comme le nom l'indique (« 4. Tester l'API des tickets »), concerne uniquement le test de vos demandes de matchmaking des joueurs reçues par le matchmaker, appelées tickets.

5. L'étape 5 (« Intégrer Matchmaking dans votre jeu ») met en évidence comment intégrer le matchmaker dans le projet de votre moteur.

Si vous rencontrez des difficultés de dépannage, notre Centre d'apprentissage approfondi propose des conseils supplémentaires sur le dépannage.

Unreal Tutorial - Adding Edgegap's Matchmaking

Si cela vous semble intimidant, nous vous couvrons - regardez la vidéo d'intégration étape par étape :

1. Configurez le niveau gratuit

Inscrivez-vous à votre compte Edgegap gratuit, et accédez à la page de tableau de bord du matchmaker.

De là, cliquez sur Créer un matchmaker d'abord, puis saisissez :

• Un nom pour votre matchmaker - qui est uniquement à titre de référence personnelle, par exemple quickstart-dev,

• Ensuite, téléchargez l'exemple simple suivant comme configuration JSON ci-dessous pour votre jeu Unity Engine :

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "simple-example": {
      "application": {
        "name": "my-game-server",
        "version": "2024.01.30-16.23.00-UTC"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 2
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 50,
              "max_latency": 200
            }
          }
        },
        "expansions": {}
      }
    }
  }
}

(rappel amical de s'assurer de changer le nom de l'application et la version pour correspondre à vos applications et versions!)

Si aucun erreur de validation n'apparaît, cliquez sur Créer et démarrer et attendez que le processus soit terminé. Cela entraînera le lancement d'un nouveau cluster gratuit, avec votre matchmaker Simple Example.

Vous pouvez maintenant passer à l'étape suivante.

2. Explorer la configuration​

Versionnement sémantique

A mesure que nous publions des mises à jour du Matchmaker, chaque nouvelle version utilise versionnement sémantique pour communiquer clairement l'impact des modifications en interprétant le format major.minor.patch :

• major versions incluent des changements cassants et nécessitent une révision d'intégration,

• minor versions incluent des améliorations rétrocompatibles substantielles,

• patch versions incluent des correctifs et de petites améliorations.

Certains déploiements peuvent entraîner des erreurs. Nous essayons de résoudre cela en réessayant de déployer jusqu'à max_deployment_retry_count fois automatiquement (sans confirmation client).

Pour s'assurer que les crashs clients inattendus ou les tickets abandonnés ne s'attardent pas et n'épuisent pas vos ressources du matchmaker, les tickets seront annulés après ticket_expiration_period causant leur statut à changer pour CANCELLED puis définitivement supprimé après ticket_removal_period.

Le cœur de notre logique de matchmaking est configuré dans Matchmaking Profiles. Chaque profil est une file d'attente de matchmaking complètement isolée, pointant vers App Versions avec une quantité prédéfinie de ressources CPU et mémoire (RAM) requises.

Règles de matchmaking dans l'ensemble de règles initiales doivent être respectées pour que les joueurs soient regroupés, chaque règle étant définie par trois propriétés :

• nom de votre choix, par exemple - taille de match,

• type de règle, également connu sous le nom d'opérateur, par exemple - player_count,

• et enfin attributs d'opérateur, par exemple team_count ou team_size.

Règle de comptage des joueurs

C'est une règle spéciale définissant combien de joueurs doivent correspondre pour initier l'affectation :

• team_count fait référence au nombre d'équipes, 1 équipe peut être utilisée pour les modes coopératifs ou free-for-all,

• team_size fait référence au nombre de joueurs par équipe.

Notre exemple simple démontre un jeu coopératif avec 2 joueurs.

est requise et ne peut être définie qu'une seule fois dans vos règles de configuration initiales.

Règles de latence

Utilisez cette règle pour fournir le ping le plus bas possible pour tous les joueurs. Une fois que les clients mesurent et soumettent leur temps de trajet aller-retour (ping) contre tous les balises disponibles, Gen2 ne considérera que les matchs dans une différence en valeurs de ping spécifiée, mesurée contre les balises ping. Cela présente une solution « souple » pour séparer votre base de joueurs, permettant de correspondre aux régions voisines, améliorant notamment la vitesse de match pour les régions moins peuplées. Utilisezmax_latency pour éviter de correspondre contre des joueurs situés trop éloignés.

Vous pouvez maintenant passer à l'étape suivante.

Notre exemple beacons règle ci-dessus avec "difference": 50, "max_latency": 200 initialement :

• Alice et Bob correspondront, puisque Pékin est écarté (> 200) et le reste est dans le | A-B | < 50 :

  • Alice {Montréal : 12.3, Newark : 45.6, Dallas : 59.9, Pékin : 264.4} ; et

  • Bob {Montréal : 27.3, Newark : 32.4, Dallas : 23.1, Pékin : 252.2}.

• Charlie et Dave ne correspondront pas, puisque | C-D | > 50 pour la balise Dallas :

  • Charlie {Montréal : 5.7, Newark : 44.2, Dallas : 59.5, Pékin : 263.2} ; et

  • Dave {Montréal : 57.8, Newark : 32.0, Dallas : 24.2, Pékin : 272.3}.

ne peuvent être définies qu'une seule fois dans vos règles de configuration initiales.

3. Examining les détails de l'instance​

Examinez les détails de votre nouveau matchmaker sur notre tableau de bord une fois qu'il est initialisé :

Statut indique la santé du service, peut être EN LIGNE, HORS LIGNE ou ERREUR.

• Identificateur aide le personnel d'Edgegap à trouver rapidement votre matchmaker si vous avez besoin d'aide pour le dépannage.

• Commencé à peut être utile pour retrouver l'heure de la dernière mise à jour.

• Taille correspond à l'un de nos niveaux de prix.

• URL API sera utilisé par les clients de jeu et les serveurs de jeu pour communiquer avec Gen2.

• URL Swagger est une spécification de openAPI GUI que nous fournissons pour explorer le schéma de l'API.

• Jeton d'authentification est un jeton secret unique utilisé par les clients de jeu et le serveur de jeu pour l'authentification.

Pour tester votre nouveau matchmaker en utilisant l'API, vous aurez besoin de l'URL Swagger, de l'URL API et du jeton Authentification.

Vous pouvez maintenant passer à l'étape suivante.

4. Tester l'API de tickets

D'abord, ouvrez votre URL Swagger pour inspecter votre schéma openAPI dans l'interface Swagger GUI

Cliquez sur l'URL /...swagger.json sous le titre « Matchmaker » pour ouvrir le schéma JSON brut :

Enregistrez cette page en tant que fichier sur votre lecteur (CTRL/CMD+S).

Ouvrez votre application Postman et connectez-vous à votre compte gratuit.

Importez votre swagger.json fichier de l'étape précédente :

• conservez Postman Collection sélectionné,

• séléctionnez voir les paramètres d'importation et changez le paramètre génération de paramètres en exemple.

Confirmez l'importation, cela entraînera l'apparition d'une nouvelle collection dans la liste des collections à gauche, intitulée Matchmaker.

Voir plus d'actions, ouvrir l'onglet autorisation et choisir :

• Type d'autorisation - API Key,

• Clé - « Authorization »

• Valeur - insérez votre valeur de jeton d'authentification ici,

• Ajouter à - Header.

Appuyez sur (CTRL/CMD+S) ou sur l'icône Enregistrer pour enregistrer les changements. Le point orange dans votre onglet Postman devrait disparaître.

Dans votre collection Matchmaker, sélectionnez tickets et créer un ticket de matchmaking, ouvrant un nouvel onglet.

Choisissez l'onglet Body pour prévisualiser votre demande de ticket de joueur:

notez player_ip définie sur null- cela entraînera l'utilisation de l'adresse IP automatiquement ajoutée à votre demande (voir intégration serveur à serveur pour les alternatives),

• profile fait référence à vos Matchmaking Profiles,

• attributes incluent des valeurs pour vos règles du matchmaker, dans ce cas pour la règle latencies,

  • règle player_count est la seule règle qui ne nécessite aucune attribution dans les tickets de joueurs.

NOTE: Assurez-vous de vous référer à la configuration d'importation Swagger du modèle. 

Cliquez sur Envoyer et passez en revue la réponse à votre demande de ticket de joueur :

• id est votre identifiant de match unique de ticket, conservez cela enregistré pour vérifier votre ticket plus tard,

• profile confirmez le choix des Matchmaking Profiles,

• group_id est un identifiant de groupe unique issu pour chaque ticket, un joueur solo est représenté comme un groupe de 1,

  • voir rejoindre en groupe pour le matchmaking avec vos amis ou lobbies,

• player_ip est l'adresse IP publique résolue du joueur, indépendamment de la méthode d'identification utilisée,

• assignment est défini sur null pour indiquer que le ticket n'a pas encore été associé ou attribué à un serveur,

• created_at donne des informations sur la création du ticket joueur à usage UI du jeu,

• status indique le statut actuel du ticket, tous les tickets commencent en SEARCHING (voir Processus de matchmaking pour les détails).

Créez un deuxième ticket en appuyant à nouveau sur Envoyer afin que nos deux joueurs se correspondent et qu'un serveur soit lancé.

Dans votre collection Matchmaker, sélectionnez {ticketId} et lisez un ticket de matchmaking.

Saisissez l'ID de ticket de la réponse de l'étape précédente et cliquez sur Envoyer.

Passez en revue l'affectation mise à jour pour votre ticket joueur :

• le statut a changé pour MATCH_FOUND d'abord, tout en maintenant assignment défini sur null pour indiquer que les joueurs se sont associés et qu'un serveur est étant attribué,

Cliquez sur Envoyer à nouveau pour vérifiez votre ticket et passez en revue l'affectation mise à jour pour votre ticket joueur :

• le statut a changé pour HOST_ASSIGNED avec assignment contenant les détails du serveur attribué.

 Inspectez votre nouveau déploiement sur notre tableau de bord:

• notez que chaque déploiement est marqué avec tous les IDs de tickets et profils pour une traçabilité supplémentaire.

Essayez de vous connecter à partir de votre client de jeu au serveur attribué.

Lorsque vous confirmez que vous êtes en mesure de vous connecter à votre déploiement sans problèmes et que vous avez terminé les tests, arrêtez votre déploiement pour libérer de la capacité dans votre compte pour la prochaine version.

Vous pouvez maintenant passer à l'étape suivante.

5. Intégrez le Matchmaker dans votre Jeu​

Le matchmaking d'Edgegap s'intègre :

• avec client de jeu, pour gérer les tickets de joueurs,

• avec serveur de jeu, pour :

  • traiter les préférences des joueurs transmises via leurs tickets,

  • optionnellement pour prendre en charge backfill pour ajouter ou remplacer les joueurs après le début.

Pour client de jeu, nous recommandons de fournir des mises à jour de statut de ticket tout au long du processus de matchmaking aux joueurs utilisant l'interface utilisateur du jeu pour la meilleure expérience du joueur. Voir :

• Edgegap - Unity Gen2 Matchmaking SDK,

  • importer l'exemple simple et personnaliser selon vos besoins,

• Betide Studio - Unreal Engine Edgegap Integration Kit,

  • télécharger le projet exemple et personnaliser selon vos besoins.

Dans client de jeu, assurez-vous de traiter les erreurs non-réessayables :

• HTTP 404 Not Found - le ticket a été supprimé,

• HTTP 500 Internal Server Error - panne temporaire du service.

Dans serveur de jeu, traitez les préférences des joueurs et le contexte initial du serveur. Aucune intégration API n'est requise :

1. Lisez les variables d'environnement injectées (Gen2) pour récupérer les données de matchmaking initiales des joueurs.

2. Lisez les variables d'environnement injectées (App Versions) pour les paramètres, les paramètres (capacité des joueurs) et les secrets spécifiques à la version.

3. Lisez les variables d'environnement injectées (Deployment) pour obtenir des informations sur le déploiement, telles que l'adresse IP, l'emplacement ou plus.

Une fois que les joueurs se connectent, serveur de jeu et clients de jeu commencent une scène de chargement pour effectuer des étapes de synchronisation (par exemple, sélectionner et charger une carte/scène/niveau). Nous recommandons une scène 3D complète, une interface utilisateur sociale de type lobby, ou un écran de chargement avec une barre de progression pour indiquer que l'initialisation progresse.

Une fois clients de jeu entièrement chargés, les joueurs chargent/voyagent vers la scène principale de jeu.

Optionnellement, serveur de jeu peut créer et gérer backfill et la capacité des joueurs (ajouter ou remplacer des joueurs qui quittent).

Assurez-vous que votre déploiement sera arrêté correctement en utilisant DELETE_URL injecté, si :

• aucun joueur ne rejoint le match,

• tous les joueurs ont quitté le match,

• le match se conclut correctement.

Félicitations, vous avez complété l'intégration Edgegap Matchmaker ! Si vous souhaitez en savoir plus, lisez tout à ce sujet dans notre Centre d'apprentissage.