Exemple de scénario
John souhaite jouer à un jeu multijoueur d’arène de combat, mais il veut une partie dans laquelle tous les utilisateurs sélectionnent leur héros au hasard. À l’aide du parcours des sessions multijoueurs, il peut récupérer une liste de sessions de jeu ouvertes et trouver celles qui incluent « héros aléatoires » dans leur description. Si l’interface utilisateur du titre propose cette option, il peut sélectionner le mode de jeu « héros aléatoire » et récupérer uniquement les sessions marquées comme parties « RandomHero ». Lorsque John trouve une session de jeu qui lui plaît, il peut la rejoindre. Une fois que suffisamment de personnes l’ont rejointe, l’hôte de la session de jeu peut la démarrer.Rôles
Une session présente dans la fonctionnalité de parcours des sessions multijoueurs peut indiquer qu’elle recrute des utilisateurs pour des rôles spécifiques. Par exemple, un utilisateur peut souhaiter créer une session de jeu qui ne contient pas plus de cinq classes d’assaut, mais qui doit contenir au moins deux rôles de soigneur et au moins un rôle de tank. Lorsqu’un autre utilisateur postule pour la session, il peut présélectionner son rôle. Le service décide alors s’il peut rejoindre la session en fonction du nombre de places disponibles pour le rôle sélectionné. Si un utilisateur souhaite réserver deux places pour que ses amis puissent le rejoindre, il peut désigner un rôle « amis » pour la session, et seuls les utilisateurs amis avec l’hôte peuvent occuper les deux places réservées au rôle « amis ». Pour plus d’informations sur les rôles, consultez Rôles multijoueurs.Fonctionnement du parcours des sessions multijoueurs
Le parcours des sessions fonctionne à l’aide de handles de recherche. Un handle de recherche est un paquet de données qui contient une référence à la session, ainsi que des métadonnées supplémentaires sur la session, comme les attributs de recherche. Lorsqu’un titre crée une session de jeu éligible au parcours des sessions multijoueurs, il crée un handle de recherche pour la session. Le handle de recherche est stocké dans le Multiplayer Service Directory (MPSD), qui gère les handles de recherche du titre. Lorsqu’un titre doit récupérer une liste de sessions, il peut envoyer une requête de recherche au MPSD, qui retourne une liste de handles de recherche répondant aux critères de recherche. Le titre peut ensuite utiliser la liste des sessions pour afficher à l’utilisateur une liste de parties qu’il est possible de rejoindre. Lorsqu’une session est complète, ou ne peut pas être rejointe pour une autre raison, votre titre peut supprimer le handle de recherche du MPSD afin que la session n’apparaisse pas dans les requêtes de parcours des sessions multijoueurs.Les handles de recherche sont utilisés pour afficher une liste de sessions à un utilisateur.
Configurer une session pour le parcours des sessions multijoueurs
Pour utiliser des handles de recherche pour une session, les propriétéssearchable et userAuthorizationStyle de la session doivent être définies sur true.
La fonctionnalité userAuthorizationStyle n’est requise que pour les jeux UWP, mais nous vous recommandons de l’implémenter pour tous les jeux XBOX, y compris les jeux Microsoft Game Development Kit (GDK). Cela garantit la portabilité future de votre titre.
Définir
userAuthorizationStyle sur true remplace la valeur none des propriétés readRestriction et joinRestriction de la session par local. Cela signifie que les titres doivent utiliser des handles de recherche ou de transfert pour rejoindre une session de jeu.Pour le parcours des sessions multijoueurs, créez des handles de recherche uniquement sur les sessions utilisées pour le jeu proprement dit. Ne les utilisez pas pour les sessions de salon.
Propriété des sessions de jeu
De nombreux types de sessions de jeu, comme SmartMatch ou une session réservée aux amis, ne nécessitent pas d’hôte ni de propriétaire. Toutefois, lors de la configuration de parties de parcours des sessions multijoueurs, vous pouvez souhaiter avoir un propriétaire. Une session gérée par un propriétaire présente certains avantages pour l’hôte, comme la possibilité de retirer d’autres membres de la session ou de modifier le statut de propriétaire d’autres membres. Pour utiliser des propriétaires pour une session, la propriétéhasOwners de la session doit être définie sur true.
Lorsque vous utilisez des rôles multijoueurs, vous pouvez faire en sorte que seuls les propriétaires puissent attribuer des rôles aux utilisateurs.
Si le propriétaire d’une session a bloqué un membre XBOX, ce membre ne peut pas rejoindre la session.
ownershipPolicy.migration définie pour celle-ci.
Si la stratégie est « oldest », l’utilisateur présent depuis le plus longtemps dans la session devient le nouveau propriétaire.
Si la stratégie est « endsession » (valeur par défaut si aucune n’est fournie), le service met fin à la session et en retire tous les utilisateurs restants.
Handles de recherche
Un handle de recherche est stocké dans le MPSD sous la forme d’une structure JSON. Outre une référence à la session, les handles de recherche contiennent également des métadonnées supplémentaires pour les recherches, appelées attributs de recherche. Une session ne peut avoir qu’un seul handle de recherche à la fois. Pour créer un handle de recherche pour une session à l’aide de l’API des services XBOX (XSAPI), appelez la méthode XblMultiplayerCreateSearchHandleAsync.Attributs de recherche
Les attributs de recherche se composent des éléments suivants.-
Les
tagssont des descripteurs sous forme de chaînes que les utilisateurs peuvent employer pour catégoriser une session de jeu, comme un hashtag.- Les tags doivent commencer par une lettre, ne peuvent pas contenir d’espaces et doivent comporter moins de 100 caractères.
- Exemples de tags : “ProRankOnly”, “norocketlaunchers”, “cityMaps”.
-
Les
stringssont des variables de texte.- Les noms de chaînes doivent commencer par une lettre, ne peuvent pas contenir d’espaces et doivent comporter moins de 100 caractères.
- Exemples de métadonnées de chaîne : “Weapons”=“knives+pistols+rifles”, “MapName”=“UrbanCityAssault”, “description”=“Fun casual game, new people welcome.”
-
Les
numberssont des variables numériques. Les XSAPI récupèrent les valeurs numériques sous le type float.- Les noms de nombres doivent commencer par une lettre, ne peuvent pas contenir d’espaces et doivent comporter moins de 100 caractères.
- Exemples de métadonnées numériques : “MinLevel” = 25, “MaxRank” = 10.
La casse des tags et des valeurs de chaîne est conservée dans le service, mais vous devez utiliser la fonction
tolower() lorsque vous interrogez des tags. Cela signifie que les tags et les valeurs de chaîne sont actuellement tous traités en minuscules, même s’ils contiennent des majuscules.Détails supplémentaires
Lorsque vous récupérez un handle de recherche, les résultats incluent également des données utiles sur la session, par exemple si la session est fermée et s’il existe des restrictions d’accès. Dans les XSAPI, ces détails, ainsi que les attributs de recherche, sont inclus dans les résultatsXblMultiplayerSearchHandle retournés après une requête de recherche.
Supprimer un handle de recherche
Lorsque vous souhaitez retirer une session du parcours des sessions multijoueurs, par exemple lorsque la session est complète ou fermée, vous pouvez supprimer le handle de recherche. Dans les XSAPI, supprimez un handle de recherche à l’aide de la méthode XblMultiplayerDeleteSearchHandleAsync.Créer un handle de recherche avec des métadonnées
Le code suivant montre comment créer un handle de recherche pour une session à l’aide des API multijoueurs XBOX.C plat
Créer une requête de recherche de sessions
Lorsque vous récupérez une liste de handles de recherche, vous pouvez utiliser une requête de recherche pour limiter les résultats aux sessions qui répondent à des critères spécifiques. La syntaxe des requêtes de recherche est une syntaxe de style OData, seuls les opérateurs suivants étant pris en charge.Vous pouvez également utiliser des expressions lambda et la fonction canonique
tolower.tolower dans la requête de recherche.
Le service ne prend en charge que la recherche de chaînes en minuscules.
Le service XBOX ne retourne que les 100 premiers résultats correspondant à la requête de recherche.
Assurez-vous que les utilisateurs puissent affiner leur requête de recherche si les résultats sont trop larges.
Les instructions
OR logiques sont prises en charge dans les requêtes de chaîne de filtre.OR est autorisé, et il doit se trouver à la racine de votre requête.
Vous ne pouvez pas avoir plusieurs instructions OR dans votre requête, ni créer une
requête dans laquelle OR ne se trouverait pas au niveau le plus élevé de la structure de la requête.
Exemples de requêtes de handles de recherche
Dans un appel REST, « Filter » est l’endroit où vous spécifiez une chaîne du langage OData Filter qui est exécutée dans votre requête sur tous les handles de recherche. Dans les API multijoueurs 2015, vous pouvez spécifier la chaîne de filtre de recherche à l’aide du paramètresearchFilter de la méthode XblMultiplayerGetSearchHandlesAsync.
Les scénarios de filtrage suivants sont actuellement pris en charge.
Actualisation des résultats de recherche
Votre jeu doit éviter d’actualiser automatiquement une liste de sessions. Donnez à l’utilisateur la possibilité d’actualiser manuellement la liste au moyen de l’interface utilisateur. Cela est utile si l’utilisateur affine ses critères de recherche pour mieux filtrer les résultats. Si un utilisateur tente de rejoindre une session complète ou fermée, votre jeu doit également actualiser les résultats de recherche.Un trop grand nombre d’actualisations de recherche peut entraîner une limitation par le service.
Rechercher des handles de recherche
Le code suivant montre comment rechercher des handles de recherche. L’API retourne une collection d’objetsXblMultiplayerSearchHandle qui représentent tous les handles de recherche correspondant à la requête.
C plat
Rejoindre une session à l’aide d’un handle de recherche
Une fois qu’un utilisateur a récupéré le handle de recherche d’une session qu’il souhaite rejoindre, assurez-vous qu’il peut s’ajouter lui-même à la session à l’aide de XblMultiplayerWriteSessionByHandleAsync.Les méthodes XblMultiplayerWriteSessionAsync ne peuvent pas être utilisées pour rejoindre une session de parcours des sessions multijoueurs.
