Comment intégrer le matchmaking à votre jeu multijoueur Party

-> Cet article est basé sur la documentation sur le matchmaking. Si vous rencontrez des problèmes ou des divergences, veuillez vous assurer de 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 matchmaking de base, à savoir :

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

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

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

Il y a cinq étapes pour mettre en œuvre notre matchmaker dans votre jeu :

1. La première étape consiste à créer un compte et à utiliser notre exemple de jeu Party. Voilà, vous êtes (techniquement) à mi-chemin ! Vous n'auriez besoin que d'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 basé sur des tours. L'étape 2 (« Explorer la configuration ») est notre « comment lire » qui aborde la fonction de chaque règles de matchmaking fonctions (« Explorer la configuration »).

3. L'étape 3 (« Examiner les détails de l'instance ») couvre votre matchmaker personnel et spécifique afin de garantir qu'il est déployé et fonctionne avec le design de votre jeu.

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

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

Si vous avez des défis de dépannage, notre centre d'apprentissage approfondi propose des conseils supplémentaires de dépannage.

1. Configurer le niveau gratuit

Inscrivez-vous pour votre compte Edgegap gratuit, et naviguez vers la page du tableau de bord du matchmaking.

Ensuite, cliquez d'abord sur Créer un matchmaker et saisissez :

• Un nom pour votre matchmaker – qui est uniquement pour votre référence, par exemple quickstart-dev,

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

{
  "version": "2.1.0",
  "inspect": true,
  "max_deployment_retry_count": 3,
  "ticket_expiration_period": "5m",
  "ticket_removal_period": "1m",
  "profiles": {
    "cooperative-example": {
      "application": {
        "name": "my-game-server=>CHANG-THIS-HERE",
        "version": "2024.01.30-16.23.00-UTC=>CHANG-THIS-HERE"
      },
      "rules": {
        "initial": {
          "match_size": {
            "type": "player_count",
            "attributes": {
              "team_count": 1,
              "team_size": 4
            }
          },
          "beacons": {
            "type": "latencies",
            "attributes": {
              "difference": 60,
              "max_latency": 60
            }
          },
          "selected_map": {
            "type": "intersection",
            "attributes": {
              "overlap": 1
            }
          },
          "selected_difficulty": {
            "type": "string_equality"
          },
          "player_level": {
            "type": "number_difference",
            "attributes": {
              "max_difference": 10
            }
          }
        },
        "expansions": {
          "5": {
            "beacons": {
              "difference": 80,
              "max_latency": 80
            }
          },
          "10": {
            "player_level": {
              "max_difference": 20
            }
          },
          "20": {
            "match_size": {
              "team_count": 1,
              "team_size": 3
            },
            "beacons": {
              "difference": 100,
              "max_latency": 100
            }
          },
          "30": {
            "match_size": {
              "team_count": 1,
              "team_size": 2
            },
            "beacons": {
              "max_latency": 200
            }
          },
          "60": {
            "match_size": {
              "team_count": 1,
              "team_size": 1
            }
          }
        }
      }
    }
  }
}

(rappel amical pour vous assurer de changer le nom de l'application et version pour correspondre à votre Application et Versions!)

Si aucune erreur de validation n'apparaît, cliquez sur Créer et démarrer et attendez que le processus se termine. Cela entraînera le démarrage d'un nouveau cluster gratuit, avec votre matchmaker d'exemple simple.

Vous pouvez maintenant passer à l'étape suivante.

2. Explorer la configuration​

Règles de jeu multijoueur Party uniques

Spécifiquement pour les jeux Party, vous pouvez définir plusieurs profils de matchmaking pour les règles et paramètres spécifiques aux modes de jeu :

• permettre aux joueurs de fournir leurs préférences de carte et de choisir une carte adaptée à tous,

• permettre aux joueurs de choisir un niveau de difficulté de jeu particulier pour convenir au niveau de compétence de chacun,

• restreindre la différence de niveau des joueurs pour aligner les joueurs ayant un degré similaire de progression dans le jeu,

• Rejoindre en groupe pour des lobbys préfabriqués ou pour remplir des équipes sans dépasser les tailles d'équipe,

• permettre une latence plus élevée pour préférer des matchs plus rapides avec de meilleures préférences de joueur granulaire,

• allouer plus de CPU ou de mémoire en utilisant différentes 🏷️ Versions de l'application quand plus de joueurs sont autorisés.

Commencez avec des conditions idéales, et étendre les restrictions pour assurer des matchs rapides :

• relâcher les restrictions de latence dans le temps pour trouver plus de joueurs,

• diminuer lentement la taille de l'équipe pour nécessiter moins de joueurs et commencer le jeu plus tôt,

  • facultativement, vous pouvez avoir le serveur remplir les places vides avec des coéquipiers IA,

• augmenter lentement la différence de niveau de joueur autorisée pour trouver plus de joueurs,

• si aucun coéquipier n'est trouvé, lancez le jeu en solo et utilisez le remplissage pour ajouter des joueurs plus tard.

Versionnage sémantique

Alors que nous publions des mises à jour pour le matchmaker, chaque nouvelle version utilise le versionnage sémantique pour communiquer clairement l'impact des changements en interprétant le format major.minor.patch :

• majeur les versions incluent des changements majeurs et nécessitent une révision de l'intégration,

• mineur les versions incluent des améliorations substantielles compatibles avec les versions précédentes,

• patch les versions incluent des corrections de bogues et des améliorations mineures.

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

Pour garantir que les plantages inattendus des clients ou les billets abandonnés ne persistent pas et n'occupent pas les ressources de votre matchmaker, les billets seront annulés après ticket_expiration_period ce qui entraîne leur statut changement à CANCELLED et ensuite définitivement supprimés après ticket_removal_period.

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

Les règles de matchmaking dans l'ensemble de règles initial doivent être respectées pour que les joueurs soient regroupés, chacune définie par trois propriétés :

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

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

• et enfin les attributs de l'opérateur, par exemple team_count ou team_size.

Règle du nombre de joueurs

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

• team_count se réfère au nombre d'équipes, 1 équipe peut être utilisée pour les modes coopératifs ou tous contre tous,

• team_size se réfère au nombre de joueurs par équipe.

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

Veuillez noter que la règle « Nombre de joueurs » est requise et ne peut être définie qu'une seule fois dans vos règles de configuration initiales.

Règle des latences

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 réponse aller-retour (ping) contre tous les balises disponibles, Gen2 ne considérera que les matchs dans une différence spécifique de valeurs de ping, mesurées contre les balises de ping. Cela présente une solution « douce » pour diviser votre base de joueurs, permettant le matchmaking avec des régions voisines, améliorant particulièrement la vitesse des matchs pour les régions moins peuplées. Utilisez max_latencypour éviter le matchmaking contre des joueurs situés loin.

Vous pouvez maintenant passer à l'étape suivante.

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

• Alice et Bob seront appariés, puisque Beijing est rejeté (>200) et le reste est dans | 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 seront pas appariés, puisque | C-D | > 50 pour la balise de Dallas :

  • Alice {Montréal : 5,7, Newark : 44,2, Dallas : 59,5, Pékin : 263,2}; et

  • Bob {Montréal : 57,8, Newark : 32,0, Dallas : 24,2, Pékin : 272,3}.

Veuillez noter que les « règles de latence » ne peuvent être définies qu'une seule fois dans vos règles de configuration initiales.

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

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

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

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

• Commencé à peut être utile pour suivre le dernier temps de mise à jour.

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

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

• URL de Swagger est une interface utilisateur de spécification openAPI pratique 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 à l'aide de l'API, vous aurez besoin de l'URL de Swagger, de l'URL de l'API et du jeton d'authentification.

Vous pouvez maintenant passer à l'étape suivante.

4. Tester l'API des billets

Tout d'abord, ouvrez votre URL de Swagger pour inspecter votre schéma openAPI dans l'interface utilisateur de Swagger

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

Enregistrez cette page sous forme de fichier sur votre disque (CTRL/CMD+S).

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

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

• gardez Postman Collection sélectionné,

• séléctionner Afficher 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, ouvrez l'onglet Autorisation et choisissez :

• Type d'auth - Clé API,

• Clé - “Authorization”

• Valeur - insérez ici votre valeur AuthToken,

• Ajouter à - Header.

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

Dans votre collection Matchmaker, sélectionnez billets et Créer un billet de matchmaking, en ouvrant un nouvel onglet.

Sélectionnez l'onglet Corps pour prévisualiser votre demande de billet joueur :

notez que player_ip est réglé sur null- cela fera en sorte que l'adresse IP soit automatiquement ajoutée à votre demande (voir Intégration Serveur à Serveur pour d'autres alternatives),

• profil se réfère à vos profils de matchmaking,

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

  • la règle player_count est la seule règle qui ne nécessite aucun attribut dans les billets de joueurs.

REMARQUE : Assurez-vous de vous référer à la configuration d'importation de l'échantillon de Swagger. 

Cliquez sur Envoyer et examinez la réponse à votre demande de billet de joueur :

• id est l'ID unique de votre billet de matchmaking, gardez ceci enregistré pour vérifier votre billet plus tard,

• profil confirmant le choix des profils de matchmaking,

• group_id est un ID de groupe unique attribué à chaque billet, un joueur solo est représenté comme un groupe de 1,

  • voir Rejoindre en groupe pour le matchmaking avec vos amis ou lobbys,

• player_ip est l'adresse IP publique résolue du joueur, quel que soit le mode d'identification utilisé,

• assignment est réglé sur null pour indiquer que le billet n'a pas encore été apparié ou attribué à un serveur,

• created_at fournit des informations sur le moment où le billet joueur a été créé pour une utilisation dans l'interface utilisateur du jeu,

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

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

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

Entrez l'ID de billet de la réponse à l'étape précédente et cliquez sur Envoyer.

Examinez l'attribution mise à jour pour votre billet de joueur :

• le statut passe à MATCH_FOUND en premier, tout en gardant assignment réglé sur null pour indiquer que les joueurs sont appariés et qu'un serveur est en cours d'attribution,

Cliquez sur Envoyer à nouveau pour vérifier votre billet, et examinez l'attribution mise à jour pour votre billet de joueur :

• le statut est passé à HOST_ASSIGNED avec assignment contenant les détails du serveur attribué.

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

• notez que chaque déploiement est étiqueté avec tous les ID de billet et profil pour une traçabilité ajoutée.

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

Une fois que vous avez vérifié que vous pouvez vous connecter à votre déploiement sans problème et que vous avez terminé les tests, arrêtez votre déploiement pour libérer de la capacité dans votre compte pour la prochaine build.

Vous pouvez maintenant passer à l'étape suivante.

5. Intégrer le matchmaker dans votre jeu​

Le matchmaking d'Edgegap s'intègre :

• avec client de jeu, pour gérer billets de joueurs,

• avec serveur de jeu, pour :

  • traiter les préférences des joueurs transmises par leurs billets,

  • facultativement pour prendre en charge le remplissage pour ajouter ou remplacer des joueurs après le démarrage.

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

• Edgegap - SDK de matchmaking Unity Gen2,

  • importer un exemple simple et personnaliser selon vos besoins,

• Betide Studio - Kit d'intégration Unreal Engine Edgegap,

  • téléchargez le projet d'exemple et personnalisez selon vos besoins.

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

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

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

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

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

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

3. Lisez Variables d'environnement injectées (Déploiement) pour les informations de déploiement, comme l'adresse IP, l'emplacement, ou plus.

Une fois que les joueurs se connectent, le serveur de jeu et les clients de jeu démarrent 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 est en cours.

Une fois que les clients de jeu sont totalement chargés, les joueurs chargent/se déplacent vers la scène de jeu principale.

Facultativement, le serveur de jeu peut créer et gérer le remplissage et la capacité des joueurs (ajouter ou remplacer des joueurs qui partent).

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 termine correctement.

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