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 est une entité qui réside sur les serveurs de l'interface Steam et qui ressemble beaucoup à une salle de chat. Les utilisateurs peuvent 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 d'autres utilisateurs de la salle. Une salle d'attente peut accueillir jusqu'à 250 utilisateurs, mais la plupart des jeux n'ont à traiter qu'entre 2 et 16 joueurs. 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 de trouver d'autres utilisateurs avec lesquels 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 ID Steam, comme pour les utilisateurs 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. L'utilisateur sélectionne le jeu auquel il souhaite jouer en multijoueur, et le type de jeu multijoueur qu'il 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 restent dans la salle jusqu'à ce qu'il y ait suffisamment de joueurs prêts à lancer le jeu. Les données des personnages choisis ainsi que d'autres données propres à chaque joueur sont partagées entre les membres de la même salle. Seul le 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 un seul joueur).
  5. Une interface utilisateur peut ou non être associée à 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 de l'API Réseau Steam.
  6. Une fois que la partie est prête à être lancée, tous les utilisateurs rejoignent le serveur de jeu ou se connectent à l'utilisateur désigné pour héberger la partie, puis quittent la salle d'attente. Une fois que tous les utilisateurs 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 connexion des utilisateurs à 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 d'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 pour un joueur, 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, soit à partir d'une recherche ou d'un ami, 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).

Lorsqu'un utilisateur rejoint ou quitte une salle d'attente, un rappel LobbyChatUpdate_t est publié à l'attention de tous les membres de cette salle, y compris au propriétaire.

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

Pour obtenir plus d'informations sur un autre utilisateur dans la salle d'attente, vous devrez utiliser l'API relative aux amis. Consultez la section Amis, 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 utilisateur aura automatiquement les dernières données de toutes les salles dont il est membre. En ce qui concerne les salles d'attente renvoyées via les résultats de recherche, l'utilisateur 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'attente d'un ami, 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 d'attente sont modifiées dans une salle, tous les membres de la salle recevront un rappel LobbyDataUpdate_t (le même rappel qui vous indique également 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 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. Ce qui envoie un simple message binaire à tous les utilisateurs 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.

Amis, invitations et salles d'attente

Vous pouvez trouver toutes les salles dont les amis d'un utilisateur sont membres grâce à l'API relative aux amis :
int cFriends = SteamFriends()->GetFriendCount( k_EFriendFlagImmediate ); for ( int i = 0; i < cFriends; 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 ami dans une salle d'attente avec ISteamMatchmaking::InviteUserToLobby.
Une boîte de dialogue avec un lien pour rejoindre la partie s'affichera pour cet utilisateur. Si l'utilisateur clique sur le lien, et qu'il n'est pas actuellement en train d'exécuter le jeu, le lien lancera le jeu avec la ligne de commande :
+connect_lobby

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

Si vous souhaitez que l'utilisateur sélectionne dans une liste les amis à inviter dans une salle d'attente, vous pouvez appeler ISteamFriends::ActivateGameOverlayInviteDialog.
Ceci qui activera l'overlay en jeu Steam et affichera une boîte de dialogue destinée à inviter les amis dans la salle d'attente actuelle.

Authentification

Tout utilisateur dans une salle d'attente est déjà authentifié sur Steam. Le jeu n'a pas besoin d'effectuer d'autres étapes d'authentification auprès des utilisateurs de la salle, sauf s'il cherche à savoir s’ils ont reçu d'un bannissement VAC (voir « Technologie Anti-triche de Valve »). Si un utilisateur 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, chaque utilisateur peut simplement quitter la salle d'attente en utilisant :
ISteamMatchmaking::LeaveLobby.
Une fois que tous les utilisateurs sont partis, la salle d'attente est automatiquement détruite dans l'interface.

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 invite un ami à jouer, ou qu'une action de l'utilisateur 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, 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 une liste de salles parmi lesquelles le joueur peut choisir. Le jeu peut également choisir automatiquement la salle à rejoindre.

D'autres questions ?

Posez vos questions sur le forum de discussion « Matchmaking Steam et salles d'attente ».