Matchmaking

Commencez rapidement avec le matchmaking et explorez des scénarios d'exemple pour différents genres.

Suivez cette vidéo pour démarrer avec notre service Matchmaker :

✔️ Préparation

Architecture du Matchmaking

Ce guide se concentrera sur l'API Matchmaking et l'API Backfill.

Il y a quatre (4) flux de données importants lorsque le matchmaking est impliqué :

1. API Matchmaking est utilisée par les clients de jeu pour communiquer avec le Matchmaker :

   1. pour la gestion des groupes, l'attribution de serveurs et la surveillance,

   2. pour la mesure du ping avec Balises de ping.

2. Déploiements L'API est utilisée pour déployer, mettre à l'échelle et gérer vos serveurs dédiés par le Matchmaker.

3. Transports Netcode sont utilisés pour communiquer entre les clients de jeu et les serveurs dédiés.

4. Regard approfondi pour remplacer ou ajouter des joueurs à un serveur en cours d'exécution.

Après la sortie, votre matchmaker devra fonctionner 24h/24 et 7j/7 pour garantir que les joueurs du monde entier puissent rejoindre des serveurs.

🍀 Exemple simple

Commencez par un exemple simple et testez le flux de joueur de base du matchmaking :

• création de l'instance du matchmaker sur le Regard approfondi,

• définition des règles et paramètres dans votre matchmaker ⚙️ Configuration,

• test du flux de joueur et gestion des tickets avec 📗 API.

1. Configuration sur le niveau gratuit

☑️ Inscrivez-vous pour votre compte Edgegap gratuit et ouvrez le page du tableau de bord Matchmaker.

☑️ Cliquez sur Créer un Matchmaker d'abord, puis saisissez :

• nom du matchmaker - pour votre référence, par ex. quickstart-dev ,

• téléchargez notre configuration JSON d'exemple simple.

🍀 Exemple simple (Configuration minimale recommandée) :

Assurez-vous de changer l'application nom et version pour correspondre à votre Applications et versions.

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

Dépannage et FAQ :

☑️ Si aucune erreur de validation n'apparaît, cliquez sur Créer et Démarrer et attendez la fin du processus. 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

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

• 🔥 majeure les versions incluent des changements incompatibles et nécessitent une revue d'intégration,

• 🌟 mineure les versions incluent des améliorations substantielles rétrocompatibles,

• 🩹 correctif les versions incluent des corrections de bugs et des améliorations mineures.

Inspecter les tickets pour mieux comprendre et déboguer les flux de matchmaking possibles pendant le développement. Nous recommandons de désactiver l'API inspect pour votre matchmaker en production.

Certaines 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 des plantages inattendus du client ou des tickets abandonnés ne restent pas et n'occupent pas les ressources de votre matchmaker, les tickets non appariés seront annulés après ticket_expiration_period ce qui provoque le changement de leur statut en ANNULÉ puis définitivement supprimés après ticket_removal_period .

Découvrez comment le matchmaker maximise le taux de remplissage des matchs et réduit les temps d'attente à moins de 10 secondes.

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

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

• nom de votre choix, par ex. - taille du match,

• type de règle, également appelé opérateur, par ex. - player_count,

• et enfin les attributs de l'opérateur, par ex. team_count ou max_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,

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

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

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

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

Règle des latences

✅ Vous pouvez maintenant passer à l'étape suivante.

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.

• Démarré le peut être utile pour retrouver l'heure de la dernière 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 votre matchmaker.

• URL Swagger est une interface pratique de spécification openAPI 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 les serveurs de jeu pour l'authentification.

Le personnel d'Edgegap ne demandera jamais vos jetons. Régénérez votre jeton si vous suspectez une faille de sécurité.

Pour tester votre nouveau matchmaker, vous aurez besoin de l'URL Swagger, de l'URL de l'API et du jeton d'authentification.

✅ Vous pouvez maintenant passer à l'étape suivante.

Pour mettre à jour vos règles de matchmaker en développement, modifiez votre configuration et redémarrez-la.

Voir ⏩ Mises à jour progressives pour les jeux en direct et les mises à jour sans interruption.

4. Tester l'API Tickets

Veuillez patienter jusqu'à 5 minutes après avoir démarré votre matchmaker pour permettre la propagation DNS de se compléter.

☑️ D'abord, ouvrez votre URL Swagger pour inspecter votre schéma openAPI dans l'interface swagger :

☑️ Cliquez sur Autoriser 🔒, collez votre Jeton d'authentification, et confirmez en cliquant sur Autoriser.

☑️ Faites défiler vers API Ticket - POST /tickets, développez et cliquez sur Essayez-le.

☑️ Prévisualisez votre requête :

• remarquez player_ip défini sur null - cela fera que le Matchmaker utilise automatiquement l'adresse IP ajoutée à votre requête (voir Serveur à Serveur pour des alternatives),

• profil se réfère à votre Profils (Files d’attente),

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

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

☑️ Cliquez sur Exécuter et examinez la réponse à votre requête de ticket joueur :

• id est votre identifiant unique de ticket de matchmaking, enregistrez-le pour vérifier votre ticket plus tard,

• profil confirmant le choix de Profils (Files d’attente),

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

• team_id est un identifiant d'équipe unique attribué à chaque joueur une fois que TEAM_FOUND le statut est atteint,

  • chaque équipe peut contenir plusieurs groupes, sans dépasser la taille d'équipe configurée,

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

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

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

• status indique le statut actuel du ticket, tous les tickets commencent en RECHERCHE .

☑️ Créez un second ticket en appuyant sur Exécuter à nouveau, afin que nos deux joueurs se correspondent et qu'un serveur soit démarré.

☑️ Réduisez POST /tickets et ouvrez GET /tickets/{ticketId}, puis cliquez sur Essayez-le.

☑️ Saisissez l'ID du ticket de la réponse à l'étape précédente et cliquez sur Exécuter.

☑️ Examinez l'attribution mise à jour pour votre ticket joueur :

• statut changé en MATCH_FOUND d'abord, tout en conservant assignment défini sur null pour indiquer que les joueurs ont été appariés et qu'un serveur est en cours d'attribution,

☑️ Cliquez sur Exécuter à nouveau pour vérifier votre ticket, et examinez l'attribution mise à jour de votre ticket :

• statut changé en HOST_ASSIGNED avec assignment contenant les détails du serveur assigné.

Dépannage et FAQ

Mon ticket est bloqué en RECHERCHE .

• Veuillez vérifier que vous avez créé suffisamment de tickets avec des critères qui se chevauchent et respectent votre configuration.

---

Mon ticket est coincé en changeant entre MATCH_FOUND et TEAM_FOUND de manière répétée.

• Les comptes du niveau gratuit sont limités à 1 déploiement à la fois. Veuillez envisager de passer à un niveau supérieur ou d'arrêter votre déploiement actuel pour en démarrer un nouveau.

---

Mon ticket passe directement à ANNULÉ.

• Votre ticket a atteint sa date d'expiration. Recréez un nouveau ticket ou augmentez la période d'expiration dans votre configuration à des fins de test.

---

Je reçois HTTP 404 Not Found en vérifiant mon ticket.

• Votre ticket a été supprimé soit par une requête DELETE, soit en atteignant sa période de suppression (commence après l'expiration du ticket, définie dans votre configuration). Recréez un nouveau ticket ou augmentez les périodes d'expiration/suppression dans votre configuration à des fins de test.

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

• remarquez que chaque déploiement est étiqueté avec tous les IDs de tickets et le profil pour une traçabilité accrue.

☑️ Essayez de vous connecter depuis votre client de jeu au serveur assigné.

Si vous rencontrez une latence élevée, votre intégration netcode peut être configurée pour simuler la latence réseau. Désactivez le VPN lors des tests pour des conditions plus réalistes et recevez un déploiement à faible latence.

☑️ 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 version.

✅ Vous pouvez maintenant passer à l'étape suivante.

Trouvez la spécification openAPI pour les tests à {matchmaker-url}/swagger/v1/swagger.json.

5. Intégration au jeu

Le matchmaker s'intègre avec :

• Client de jeu, pour gérer les groupes, les adhésions, les attributions et les tickets,

• Serveur dédié, pour Regard approfondi après qu'un joueur quitte.

☑️ Dans Client de jeu, nous recommandons de fournir des mises à jour du statut des tickets aux joueurs via l'interface utilisateur en jeu pour une meilleure expérience. Voir :

☑️ Dans Client de jeu, assurez-vous de gérer les erreurs réessayables 429 Trop de requêtes avec un backoff exponentiel et une nouvelle tentative, laissant le matchmaker récupérer pendant des pics de trafic soudains.

☑️ Dans Client de jeu, assurez-vous de gérer les erreurs non réessayables :

• 404 Introuvable - le ticket a été supprimé,

• 500 Erreur interne du serveur - panne temporaire du service.

☑️ Dans Serveur de jeu, lisez les préférences des joueurs et le contexte initial du serveur :

1. Variables injectées (Matchmaker) pour récupérer les données initiales de matchmaking des joueurs.

2. Variables injectées (Versions de l'application) pour les paramètres de version, les paramètres et les secrets.

3. Variables injectées (Déploiement) pour les informations de déploiement, IP, emplacement, etc...

☑️ Une fois que les joueurs sont connectés, Serveur de jeu et clients de jeu démarrent une scène de chargement - scène 3D, une interface sociale de type lobby, ou un écran de chargement avec une barre de progression, pour indiquer que l'initialisation progresse.

☑️ Assurez-vous que votre déploiement sera arrêté correctement une fois le match conclu.

🙌 Félicitations, vous avez terminé l'intégration du matchmaking ! Pour en savoir plus, continuez la lecture.

🏁 Exemple avancé

Une configuration complète utilisant toutes les fonctionnalités de matchmaking y compris Profils (Files d’attente), Règles, et Regard approfondi peut ressembler à ceci :

🎾 Lobby personnalisé

Les lobbies personnalisés (lobbies privés, niveaux bac à sable) sont une option très populaire pour le multijoueur en canapé et pour tester de nouvelles fonctionnalités dans les jeux avant qu'elles n'entrent dans les principaux modes de jeu. Ils nécessitent généralement le moins de restrictions, mais visent à garantir que les joueurs peuvent Regard approfondi.

Pour les lobbies privés sans accès public, définissez "team_size": 1 et faites en sorte que le propriétaire du groupe lance le jeu seul. Le propriétaire peut partager les détails du groupe et de l'affectation de l'hôte à n'importe quel nombre de membres pour qu'ils rejoignent.

Ajouter custom-lobby-example profil dans votre matchmaker existant pour prendre en charge les lobbies personnalisés.

🥛 Vitrine Backfill

En s'appuyant sur Matchmaking, cette configuration présente Backfill avec Groupes.

⚔️ Jeux compétitifs

Les jeux compétitifs se concentrent sur la compétition entre joueurs pour obtenir la victoire, que ce soit individuellement (tout le monde contre tout le monde) ou en équipe. Assurez des matchs équitables et équilibrés en appariant des joueurs ou des équipes de niveaux de compétence similaires, et maintenez le rythme du jeu en trouvant rapidement une compétition équitable.

Vous pouvez définir plusieurs équipes avec 1 joueur ou plus chacune, par exemple :

Mode de jeu	Nombre d'équipes	Taille d'équipe	Joueurs totaux
FPS 5v5	2	5	10
MOBA 5v5	2	5	10
Battle Royale 20x3	20	3	60
Free For All 10 joueurs	1	10	10

Définir plusieurs Profils (Files d’attente) pour des règles et paramètres spécifiques au mode de jeu, et étendre selon les besoins.

• Pour tous les matchs :

  • restreindre latence de matchmaking pour éviter d'apparier des joueurs éloignés,

  • Regard approfondi pour les groupes préformés et empêcher de dépasser les tailles d'équipe,

  • relâcher lentement les restrictions de latence au fil du temps pour trouver plus de joueurs,

  • allouer plus de CPU ou de mémoire avec différents Applications et versions pour des profils spécifiques,

• Pour les matchs occasionnels :

  • omettre les restrictions de rang pour maximiser la vitesse de correspondance et le taux de remplissage des matchs,

  • laisser les joueurs fournir leurs préférences de carte pour trouver une carte adaptée à tous,

  • spécifier la taille du groupe de backfill pour remplacer les partants sans dépasser les tailles d'équipe,

  • supprimer les limitations de latence pour garantir un match après 3 minutes (180s) de temps d'attente.

• Pour les matchs compétitifs :

  • restreindre le rang pour n'autoriser que des adversaires de niveau de compétence similaire,

  • utiliser des montées ou descentes de rangs pour apparier les joueurs aux extrémités du classement de la ligue.

• Pour le top 1 % des matchs de haute compétence (challengers) :

  • utiliser des évaluations de compétence numériques (ELO) pour obtenir un contrôle fin sur la distribution des compétences dans les matchs,

  • attendre plus longtemps avant de relâcher les exigences de latence en raison du nombre réduit de joueurs.

Utiliser plusieurs profils pour séparer les modes de jeu occasionnels, les modes compétitifs et les challengers de haut niveau joueurs vous permet de personnaliser les règles et les expansions pour chaque type de joueur séparément.

🤝 Jeux coopératifs

Les jeux coopératifs exigent que les joueurs travaillent ensemble en équipe vers un objectif commun, ou contre un adversaire IA. Alignez des joueurs ayant des préférences et des habitudes de jeu similaires. Remplacez les joueurs qui partent, et améliorez Balises de ping pour offrir une expérience joueur réactive.

Avec un nombre d'équipes de 1 et une taille d'équipe maximale de 4, exige jusqu'à 4 joueurs par match.

Définir plusieurs Profils (Files d’attente) pour les règles et paramètres spécifiques aux modes de jeu :

• commencez avec un minimum de 4 joueurs pour maintenir les joueurs en file et maximiser le taux de remplissage des matchs,

• restreindre latence de matchmaking pour éviter d'apparier des joueurs éloignés,

• laissez les joueurs choisir une difficulté de jeu particulière pour convenir au niveau de compétence de chacun,

• laisser les joueurs fournir leurs préférences de carte pour trouver une carte adaptée à tous,

• restreindre la différence de niveau des joueurs pour exiger un degré de progression similaire,

• spécifier la taille du groupe de backfill pour remplacer les partants sans dépasser la capacité du serveur,

• utiliser des indicateurs de modération pour séparer les joueurs à faible karma et les tricheurs de la population générale,

• Regard approfondi pour les groupes préformés et pour remplir les équipes sans dépasser la capacité du serveur,

• allouer plus de CPU ou de mémoire en utilisant différents Applications et versions pour d'autres profils.

Commencez par les conditions idéales, et étendez les restrictions pour assurer des matchs rapides :

• relâchez les restrictions de latence au fil du temps pour trouver plus de joueurs,

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

• diminuez la taille d'équipe minimale pour exiger moins de joueurs et lancer le jeu plus tôt,

  • le serveur peut remplir les emplacements vides avec des coéquipiers IA,

  • ou Regard approfondi pour ajouter des joueurs plus tard,

• définissez la taille d'équipe minimale à 1 pour lancer le jeu en solo après 150s de temps d'attente

🎈 Jeux sociaux

Les jeux sociaux se concentrent sur la création de liens et de relations entre les joueurs par la collaboration, la communication et l'expérience partagée. Prenez en charge un grand nombre de joueurs, maximisez le taux de remplissage des matchs et alignez les préférences et habitudes de jeu des joueurs. Remplacez les joueurs qui partent, et assurez une haute Balises de ping pour offrir une expérience joueur réactive.

Avec un nombre d'équipes de 1 (free for all) et une taille d'équipe maximale de 50, exige jusqu'à 50 joueurs par match.

Définir Profils (Files d’attente) pour les règles et paramètres spécifiques aux modes de jeu :

• restreindre latence de matchmaking pour éviter d'apparier des joueurs éloignés,

• laissez les joueurs indiquer leurs préférences de mode de jeu et trouvez un mode adapté à tous,

• spécifier la taille du groupe de backfill pour remplacer les partants sans dépasser la capacité du serveur,

• utiliser des indicateurs de modération pour séparer les joueurs à faible karma et les tricheurs de la population générale,

• Regard approfondi pour les lobbies préformés ou pour remplir les équipes sans dépasser la capacité du serveur,

• allouer plus de CPU ou de mémoire en utilisant différents Applications et versions pour d'autres profils.

Commencez par les conditions idéales, et étendez les restrictions pour assurer des matchs rapides :

• relâchez les restrictions de latence au fil du temps pour trouver plus de joueurs,

• diminuez lentement la taille d'équipe minimale pour exiger moins de joueurs et lancer le jeu plus tôt,

  • le serveur peut remplir les emplacements vides avec des joueurs IA,

  • ou Regard approfondi pour ajouter des joueurs plus tard,

• définissez la taille d'équipe minimale à 1 pour lancer le jeu en solo après 150s de temps d'attente