Documentation Steamworks
Matchmaking Steam et salles d'attente

Présentation

Le matchmaking en pair-à-pair de Steam est construit autour du concept de salle d'attente (lobby). Une salle d'attente est une entité qui réside sur les serveurs de l'interface Steam et qui ressemble beaucoup à une salle de chat. Toute personne peut créer une nouvelle salle, associer des données à une salle, chercher des salles en fonction de ces données et partager des informations avec les autres personnes présentes dans la salle. Une salle d'attente peut accueillir jusqu'à 250 personnes, mais la plupart des jeux n'ont à traiter qu'entre 2 et 16 joueurs et joueuses. Le matchmaking fondé sur les compétences repose sur ce système.

L'API de matchmaking en pair-à-pair de Steam est un ensemble de fonctions permettant aux utilisateurs et utilisatrices de trouver d'autres personnes avec lesquelles jouer. Les fonctions de matchmaking résident toutes dans ISteamMatchmaking, qui contient plus de détails sur les paramètres de chaque fonction. Les salles d'attente sont toutes identifiées avec un SteamID unique, comme pour les comptes ou les serveurs de jeu. L'exemple de Steamworks illustre l'implémentation complète et fonctionnelle des salles.

Flux du processus de matchmaking

Le modèle habituel pour amener des groupes à jouer ensemble est le suivant :
  1. La personne qui joue sélectionne le jeu auquel elle souhaite jouer en multijoueur et le type de jeu multijoueur qu'elle souhaite (règles, scénario, etc.).
  2. Le jeu recherche les salles d'attente qui ont des règles similaires, à l'aide de l'API de recherche de salles.
  3. Si une salle est trouvée, le jeu la rejoint. Si aucune salle n'est trouvée, il en crée une nouvelle.
  4. Les utilisateurs et utilisatrices restent dans la salle jusqu'à ce qu'il y ait suffisamment de personnes prêtes à lancer le jeu. Les données des personnages choisis ainsi que d'autres données propres à chaque compte sont partagées entre les membres de la même salle. Seule la personne propriétaire de la salle peut gérer les règles mises en œuvre dans la salle (par exemple, un personnage ne peut être choisi que par une seule personne).
  5. Une interface d'utilisation peut être associée ou non à la salle d'attente. Le cas échéant, les fonctions de communication de données de la salle peuvent être utilisées pour envoyer des messages de chat entre les membres de la salle. Des données vocales peuvent également être envoyées, mais elles doivent être envoyées à l'aide d'une API réseau Steam.
  6. Une fois que la partie est prête à être lancée, toutes les personnes rejoignent le serveur de jeu ou se connectent à l'utilisatrice ou l'utilisateur désigné pour héberger la partie, puis quittent la salle d'attente. Une fois que toutes les personnes ont quitté la salle, elle est automatiquement détruite.

Recherche de salles d'attente

Pour permettre à votre jeu de rechercher une salle d'attente, vous devez appeler ISteamMatchmaking::RequestLobbyList.
Cette fonction est asynchrone et renvoie un handle « SteamAPICall_t » que vous pouvez utiliser pour suivre l'état de la requête. En fonction de la qualité de la connexion à l'interface Steam, cet appel peut prendre entre 300 ms et 5 secondes pour s'achever, avec un délai de 20 secondes.
Le nombre de résultats renvoyés se trouve dans le résultat d'appel LobbyMatchList_t, que vous pouvez ensuite utiliser dans ISteamMatchmaking::GetLobbyByIndex pour effectuer une itération de chacun d'eux et obtenir leur ID.
Il peut y avoir jusqu'à 50 résultats, mais généralement, seuls deux ou trois sont renvoyés. Les résultats renvoyés sont classés par distance géographique et sont basés sur les filtres de proximité définis. Par défaut, nous ne renverrons pas de salles déjà pleines, et le filtre de distance est défini sur k_ELobbyDistanceFilterDefault (à proximité). Pour ajouter des filtres, avant d'appeler RequestLobbyList , vous devrez appeler une ou plusieurs des fonctions de filtrage ci-dessous.

Créer une salle d'attente

D'une manière générale, lorsque vous n'arrivez pas à trouver une salle d'attente pour une personne, c'est à vous d'en créer une. Appelez simplement
ISteamMatchmaking::CreateLobby et attendez que l'appel se termine. Le résultat de l'appel indique s'il a réussi. Le cas échéant, il renverra le SteamID de la salle d'attente dans une structure LobbyCreated_t, qui pourra ensuite être utilisée pour définir des métadonnées de la salle d'attente. Après avoir créé une salle, vous devrez définir ses données pour que les autres clients de jeu puissent s'en servir pour rechercher la salle (voir ci-dessous).

Rejoindre une salle d'attente

Si vous avez trouvé une bonne salle à partir d'une recherche ou d'un contact, vous pouvez utiliser ISteamMatchmaking::JoinLobby et attendre le résultat d'appel de LobbyEnter_t. Une fois dans la salle, vous devrez utiliser l'API de données de salle d'attente pour obtenir des détails sur cette salle et définir ce qui doit être affiché (si des données sont à afficher).

Lorsque quelqu'un rejoint ou quitte une salle, un rappel LobbyChatUpdate_t est publié à l'attention de l'ensemble des membres de cette salle, y compris du compte propriétaire.

Pour itérer sur les personnes qui sont actuellement dans la salle, utilisez :

Pour obtenir plus d'informations sur une autre personne dans la salle, vous devrez utiliser l'API relative aux contacts. Consultez la section Contacts, invitations et salles d'attente de la documentation pour plus de détails.

Métadonnées de la salle d'attente

Les métadonnées de la salle vous permettent de définir l'état arbitraire de la salle, notamment le nom de la salle, la carte actuelle, le mode de jeu, l'état actuel du jeu ou toute autre information à laquelle vous pouvez penser.

Un compte utilisateur recevra automatiquement les dernières données de toutes les salles dont il est membre. En ce qui concerne les salles renvoyées via les résultats de recherche, il recevra les données de la salle qui correspondent au moment où il a effectué la recherche. S'il s'agit de la salle d'un contact, aucune donnée ne sera disponible jusqu'à ce que l'API ISteamMatchmaking::RequestLobbyData soit appelée et que l'appel soit terminé avec succès.

Si les données de salle sont modifiées dans une salle, l'ensemble des membres de la salle recevra un rappel LobbyDataUpdate_t (le même rappel qui vous indique qu'un appel ISteamMatchmaking::RequestLobbyData est terminé).

Voici l'ensemble de fonctions que vous pouvez utiliser pour obtenir et définir les données d'une salle d'attente. Seul le compte propriétaire de la salle peut définir ou supprimer les données de la salle.

Voici les fonctions qui vous permettent d'itérer sur les métadonnées (elles ne sont généralement utilisées qu'à des fins de débogage) :

Les salles d'attente permettent également aux membres de définir leurs propres métadonnées pour lesquelles les autres membres peuvent recevoir des mises à jour avec les fonctions suivantes :

Communication au sein d'une salle d'attente

Pour envoyer des informations au sein d'une salle (messages, signaux de début de partie, etc.), vous devez appeler ISteamMatchmaking::SendLobbyChatMsg afin d'envoyer un simple message binaire à toutes les personnes de la salle. Les membres de la salle doivent écouter le rappel ISteamMatchmaking::LobbyChatMsg_t. Après avoir reçu le rappel, vous pouvez utiliser ISteamMatchmaking::GetLobbyChatEntry pour récupérer le contenu du message.

Contacts, invitations et salles d'attente

Vous pouvez trouver toutes les salles dont les contacts d'un utilisateur ou d'une utilisatrice sont membres grâce à l'API relative aux contacts :
int cFriends = SteamFriends()->GetFriendCount( k_EFriendFlagImmediate ); for ( int i = 0; i { FriendGameInfo_t friendGameInfo; CSteamID steamIDFriend = SteamFriends()->GetFriendByIndex( i, k_EFriendFlagImmediate ); if ( SteamFriends()->GetFriendGamePlayed( steamIDFriend, &friendGameInfo ) && friendGameInfo.m_steamIDLobby.IsValid() ) { // friendGameInfo.m_steamIDLobby est une salle valide, vous pouvez la rejoindre ou utiliser RequestLobbyData() pour obtenir ses métadonnées } }

Vous pouvez inviter un contact dans une salle d'attente avec ISteamMatchmaking::InviteUserToLobby.
Une boite de dialogue avec un lien pour rejoindre la partie s'affichera pour cette personne. Si cette dernière clique sur le lien et qu'elle n'est pas actuellement en train d'exécuter le jeu, le lien lancera le jeu avec la ligne de commande :
+connect_lobby . Assurez-vous que votre application exécute ISteamApps::GetLaunchCommandLine afin de pouvoir désactiver le message d'avertissement lors du lancement via une ligne de commande.

Si la personne est déjà dans un jeu, un rappel ISteamFriends::GameLobbyJoinRequested_t sera publié, contenant le SteamID de la salle d'attente qu'elle souhaite rejoindre. C'est à votre jeu de décider de lui obéir ou non.

Si vous souhaitez offrir la possibilité de sélectionner des contacts dans une liste pour les inviter dans une salle d'attente, vous pouvez appeler ISteamFriends::ActivateGameOverlayInviteDialog.
Cet appel activera l'overlay en jeu Steam et affichera une boite de dialogue destinée à inviter les contacts dans la salle d'attente actuelle.

Authentification

Toute personne dans une salle d'attente est déjà authentifiée sur Steam. Le jeu n'a pas besoin d'effectuer d'autres étapes d'authentification auprès des personnes de la salle, sauf s'il cherche à savoir si elles ont reçu un bannissement VAC (voir la technologie antitriche de Valve). Si l'une d'entre elles tente de se connecter depuis un autre endroit avec le même compte, ses informations de connexion précédentes seront supprimées de toutes les salles existantes.

Nettoyage des fichiers

Une fois la partie lancée, tout le monde peut quitter la salle d'attente en utilisant :
ISteamMatchmaking::LeaveLobby.
Une fois toutes les personnes parties, la salle d'attente est automatiquement détruite côté serveur.

Conseils pour les salles d'attente

  • D'une manière générale, vous ne devez créer des salles d'attente que lorsque c'est nécessaire. Par exemple, lorsque l'utilisateur ou l'utilisatrice invite un contact à jouer, ou qu'une de ses actions nécessite la création d'une salle.
  • Ne mettez pas à jour les métadonnées des salles trop souvent. N'ajoutez que les métadonnées et les valeurs qui sont utilisées pour effectuer une recherche (par exemple, le type de jeu ou l'état du jeu). Vous n'avez pas besoin de spécifier le nombre de joueurs et de joueuses, car une recherche de salle d'attente sélectionne les salles avec des places disponibles.
  • Ne rejoignez pas une salle d'attente simplement pour découvrir ses métadonnées. Les métadonnées de salles peuvent être téléchargées séparément pour toutes les salles. Votre jeu peut ensuite utiliser ces données pour afficher la liste des salles que le joueur ou la joueuse peut choisir. Le jeu peut également choisir automatiquement la salle à rejoindre.

D'autres questions ?

Posez vos questions sur le forum de discussion à propos du matchmaking Steam et des salles d'attente.