Objets PlayFab Party et leurs relations

Tirer pleinement parti de la puissance et de la flexibilité de l’API PlayFab Party commence par la compréhension des objets essentiels suivants définis dans son périmètre :

• Appareil : une instance distincte du jeu s’exécutant sur un appareil physique. Un appareil local existe dès que l’API est utilisée.
• Utilisateur : un joueur individuel connecté, ou plus précisément, une entité PlayFab title_player_account que le jeu fournit à PlayFab Party à des fins d’authentification et d’identification. Un ou plusieurs utilisateurs sont associés à un appareil donné.
• Réseau : un ensemble sécurisé d’un ou de plusieurs appareils et de leurs utilisateurs autorisés, créé par le jeu pour échanger des communications de clavardage ou de données. Un réseau correspond généralement au concept de session multijoueur ou de groupe de clavardage d’un jeu.
• Point de terminaison : une abstraction permettant d’envoyer et de recevoir des données au sein d’un réseau. Un point de terminaison peut représenter un appareil, un utilisateur ou tout concept propre au jeu.
• Contrôle de clavardage : une représentation d’un utilisateur destinée spécifiquement à configurer, émettre et cibler le clavardage vocal et textuel dans un ou plusieurs réseaux.

​

Relations entre les objets

Selon une hiérarchie conceptuelle simplifiée, les réseaux contiennent des appareils, qui contiennent à leur tour des utilisateurs, des points de terminaison facultatifs et des contrôles de clavardage facultatifs. Par exemple : Bien qu’assez simple à comprendre, le diagramme de relations précédent est en réalité une représentation incomplète des capacités de PlayFab Party et peut être trompeur s’il est considéré isolément. En réalité, l’API Party permet aux appareils de se connecter à plusieurs réseaux à la fois. Par exemple, on peut souhaiter maintenir la communication avec un groupe d’amis dans la durée, pendant que ce même groupe rejoint et quitte des sessions de jeu distinctes plus importantes avec des inconnus. Envisager ce scénario plus large nous permet de mieux saisir les relations entre ces objets. Il peut sembler intuitif de concevoir un appareil comme appartenant à des réseaux, mais ce n’est pas le cas. Il est plus juste de considérer que les appareils participent à des réseaux. Ainsi, la bibliothèque Party ne crée jamais qu’un seul objet d’API d’appareil, distant ou local, lorsqu’une instance particulière est rencontrée, quel que soit le nombre de réseaux qu’elle partage avec votre appareil local. À titre d’exemple, le diagramme suivant montre deux réseaux et trois appareils avec des utilisateurs, des contrôles de clavardage et des points de terminaison. L’appareil A et ses deux contrôles de clavardage (avec les utilisateurs associés) participent au réseau 1, tandis que les appareils B et C se sont connectés à la fois au réseau 1 et au réseau 2 avec un seul contrôle de clavardage (et l’utilisateur associé) chacun. Tous les appareils ont créé un ou deux points de terminaison dans chaque réseau auquel ils sont connectés : Dans le diagramme, chaque appareil voit une seule instance de chacun des trois appareils et de leurs contrôles de clavardage, puisqu’ils ont au moins un réseau en commun. L’appareil A ne connaît que les points de terminaison 1 à 4 du réseau 1, mais les appareils B et C peuvent également voir les points de terminaison 5 à 7 qu’ils ont créés dans le réseau 2. Si l’appareil C ne participait qu’au réseau 2 et non aux deux réseaux :

• L’appareil C ne pourrait évidemment pas créer le point de terminaison 4 dans le réseau 1, ni voir les points de terminaison 1 à 3.
• L’appareil C ne connaîtrait pas l’appareil A ni ses deux contrôles de clavardage, présents uniquement dans le réseau 1.
• De même, l’appareil A ne verrait pas l’appareil C ni son contrôle de clavardage, présents uniquement dans le réseau 2.

L’appareil B, en revanche, verrait toujours tous les appareils et leurs contrôles de clavardage, puisqu’il se trouve toujours dans les deux réseaux. Ainsi, bien que les appareils et les contrôles de clavardage se situent « en dehors » d’une relation hiérarchique stricte avec les réseaux, il est important de noter qu’une instance de jeu ne rencontrera jamais réellement un appareil ou un contrôle de clavardage distant sans le contexte d’un réseau associé. Si l’appareil ou le contrôle de clavardage local et distant ont au moins un réseau en commun, l’objet distant peut être visible. En revanche, s’il n’y a aucun réseau commun, l’objet distant ne sera jamais créé.

​

Attributs communs des objets

Tous les objets ont des durées de vie bien définies. Une instance de jeu locale crée et détruit chaque objet directement ou à l’aide de mécanismes de notification standardisés qui ne sont signalés que pendant une fenêtre de temps choisie par le jeu. L’utilisation des notifications est décrite plus en détail dans une rubrique ultérieure. Tous les objets de l’API PlayFab Party prennent également en charge le concept de contexte personnalisé, qui est simplement un moyen de stocker avec l’objet un pointeur ou une valeur « raccourci » facultatif, uniquement local. Les contextes personnalisés permettent de passer facilement des objets PlayFab Party aux objets de jeu privés correspondants en mémoire (le cas échéant), sans avoir à effectuer une recherche inefficace. Ces valeurs ne sont pas transmises à distance, car les valeurs de pointeur n’ont de sens que pour l’instance de jeu locale. Enfin, tous les objets ci-dessus, à l’exception du réseau, disposent d’un sous-objet spécialisé « Local » contenant des méthodes et des propriétés disponibles uniquement pour l’appareil local propriétaire de l’objet. Par exemple, il existe un objet de base PartyEndpoint utilisé pour représenter n’importe quel point de terminaison local ou distant, ainsi qu’un objet plus spécifique PartyLocalEndpoint qui ne peut être récupéré au moyen de PartyEndpoint::GetLocal() que si ce point de terminaison a effectivement été créé par l’appareil local. C’est là qu’est exposée la méthode PartyLocalEndpoint::SendMessage() permettant de transmettre des données de jeu, car il n’aurait aucun sens qu’un appareil puisse d’une façon ou d’une autre transmettre des données depuis les points de terminaison sources d’un autre appareil distant. Lorsque vous utilisez l’interface C++ de PlayFab Party (recommandée), les objets sont exposés sous forme d’instances de classes C++. Lorsque vous utilisez l’interface C plate, les objets sont représentés par des valeurs de handle.

​

Rôles détaillés de tous les objets principaux

1. Gestionnaire (PartyManager)
2. Réseau (PartyNetwork)
3. Appareil (PartyDevice et PartyLocalDevice)
4. Utilisateur (ID d’entité utilisateur et PartyLocalUser)
5. Point de terminaison (PartyEndpoint et PartyLocalEndpoint)
6. Contrôle de clavardage (PartyChatControl et PartyLocalChatControl)
7. Changement d’état (PartyStateChange)

​

Gestionnaire

En plus des objets résumés précédemment, l’API PlayFab Party expose également un objet singleton de niveau supérieur, PartyManager. Cet objet utilitaire et organisationnel sert en grande partie de point de départ pour commencer à travailler avec les autres objets. C’est par exemple dans le gestionnaire que les nouveaux réseaux et les utilisateurs locaux sont initialement créés. Toutes les fins d’opérations asynchrones et toutes les notifications y sont également centralisées. Plus fondamentalement, c’est dans le gestionnaire que la bibliothèque PlayFab Party elle-même est initialisée avant son utilisation et nettoyée lorsqu’elle n’est plus nécessaire.

​

Réseau

Un objet PartyNetwork représente un ensemble sécurisé d’appareils participants, de leurs utilisateurs autorisés, ainsi que des points de terminaison ou contrôles de clavardage associés. Les réseaux sont initialement créés vides, puis des appareils s’y connectent et authentifient au moins un utilisateur local dans le réseau. Les réseaux qui n’ont aucun utilisateur authentifié sont automatiquement détruits après un délai d’expiration. Pour pouvoir s’y connecter, les réseaux sont référencés à l’aide de descripteurs de réseau. Les descripteurs de réseau sont des structures binaires en grande partie opaques contenant les informations dont PlayFab Party a besoin en interne pour identifier et localiser le réseau. L’API fournit des méthodes pour sérialiser ces structures en chaînes adaptées aux services web et inversement, afin qu’elles puissent être échangées avec d’autres appareils à l’aide des mécanismes d’invitation courants des plateformes sociales, de PlayFab Matchmaking ou d’autres mécanismes de rendez-vous externes ne relevant pas de PlayFab Party lui-même. Même avec un descripteur de réseau, l’accès à un réseau est limité aux utilisateurs autorisés. Cette autorisation des utilisateurs s’effectue lors de la création du réseau, puis par la création et la révocation ultérieures d’invitations, comme décrit plus en détail dans la rubrique Invitations et modèle de sécurité. Les jeux peuvent choisir d’utiliser des invitations pour limiter l’accès aux seuls amis des utilisateurs, ou pour empêcher des joueurs malveillants de rejoindre le réseau. Les appareils peuvent se connecter à plusieurs réseaux à la fois. Vous pouvez en savoir plus sur l’opportunité et la façon d’utiliser plusieurs réseaux dans une rubrique ultérieure. Les types d’actions pouvant être effectuées sur les objets PartyNetwork incluent l’authentification d’utilisateurs locaux dans le réseau, la connexion et l’énumération de contrôles de clavardage, la création et l’énumération de points de terminaison, ou l’obtention d’informations de performances à l’échelle du réseau.

​

Appareil

L’objet PartyDevice représente une instance distincte du jeu et de son code de bibliothèque PlayFab Party s’exécutant sur un appareil physique. La plupart des opérations ne sont pas effectuées sur les objets PartyDevice eux-mêmes; ceux-ci constituent plutôt un mécanisme organisationnel permettant de définir quels points de terminaison ou contrôles de clavardage appartiennent à cette instance de jeu, en particulier pour les plateformes et les jeux qui prennent en charge plusieurs utilisateurs locaux simultanément. PlayFab Party utilise la connaissance de ces relations pour optimiser la transmission des données de jeu et du clavardage, par exemple en n’envoyant qu’une seule copie d’un message même si plusieurs cibles de l’appareil doivent le recevoir. Les objets PartyDevice distants sont des « sous-produits » de la connexion à un réseau et de l’authentification d’un utilisateur dans ce réseau. Ils ne sont créés que lorsque des utilisateurs distants valides et authentifiés associés à l’appareil participent à un réseau auquel l’appareil local est également connecté. De même, ils sont détruits dès que ce n’est plus le cas. En revanche, le sous-objet spécialisé PartyLocalDevice est toujours disponible pour que l’instance de jeu locale puisse y faire référence tant que PlayFab Party est initialisé. Il n’est jamais explicitement créé ni détruit.

​

Utilisateur

Un utilisateur PlayFab Party est un joueur humain unique pour lequel le jeu effectue une connexion de joueur PlayFab afin d’obtenir un ID d’entité title_player_account et un jeton. Les utilisateurs distants sont identifiés dans l’API PlayFab Party uniquement par la chaîne de leur ID d’entité associée aux contrôles de clavardage et éventuellement aux points de terminaison. Ils ne sont pas représentés par un objet dédié. En effet, PlayFab Party ne dispose d’aucune fonctionnalité interagissant de façon significative avec des utilisateurs arbitraires, si ce n’est pour une identification brute et comme étiquette associée à ces autres objets. À l’inverse, pour les utilisateurs locaux, il existe des objets PartyLocalUser explicites, car les jeux gèrent eux-mêmes leur durée de vie dans PlayFab Party. Le jeu crée généralement un PartyLocalUser lorsqu’il a connecté avec succès ce joueur PlayFab à l’aide de la méthode de connexion applicable, et détruit le PartyLocalUser le moment venu lorsque cet utilisateur se déconnecte. Pour les plateformes et les jeux qui prennent en charge plusieurs joueurs locaux connectés, des objets PartyLocalUser supplémentaires doivent être créés pour chaque joueur. Les objets PartyLocalUser sont également importants, car ils constituent la base de toute authentification. Un utilisateur local valide doit exister pour pouvoir créer un nouveau réseau ou s’authentifier dans un réseau. L’autorisation des utilisateurs est décrite plus en détail dans la rubrique consacrée aux invitations et au modèle de sécurité. Presque toutes les opérations nécessitent qu’un PartyLocalUser soit fourni ou présent, même si très peu d’opérations sont effectuées sur les objets PartyLocalUser eux-mêmes. Les objets PartyLocalUser sont créés à l’aide de l’objet PartyManager. Ils ne peuvent être détruits explicitement que par leurs créateurs. Bien qu’ils n’aient pas de représentation objet directe sur les appareils distants, les contrôles de clavardage et les points de terminaison qui leur sont associés sont détruits si l’appareil propriétaire retire le PartyLocalUser ou se déconnecte du réseau, proprement ou non.

​

Point de terminaison

Les objets PartyEndpoint sont facultatifs, mais ils sont au cœur de la communication de données PlayFab Party pour les jeux qui les utilisent. Comme les sockets réseau classiques, les points de terminaison sont un mécanisme d’adressage abstrait permettant d’émettre ou de cibler des messages de données au sein d’un réseau. Ils peuvent représenter un appareil, un utilisateur individuel ou tout concept arbitraire défini par le jeu (par exemple, une unité de char) que vous souhaitez identifier de façon unique pour envoyer et recevoir des messages. Le sous-objet spécialisé PartyLocalEndpoint concerne les points de terminaison créés dans le réseau par l’instance de jeu locale. C’est là que réside l’essentiel des fonctionnalités des points de terminaison. Sa méthode PartyLocalEndpoint::SendMessage() transmet des charges utiles de données de jeu du PartyLocalEndpoint vers un ou plusieurs autres objets PartyEndpoint du même réseau. Elle fournit diverses options permettant de choisir la meilleure façon de gérer la perte de paquets sur Internet (par exemple, garantir la remise et/ou l’ordre), de contrôler le compromis entre une faible latence et le regroupement de plusieurs messages provenant du même point de terminaison local ou d’autres pour réduire l’utilisation de la bande passante, et de réagir lorsque la qualité de la connexion n’est pas suffisante pour prendre en charge le débit d’envoi du jeu. En plus d’être lui-même une source ou une destination de messages de données, chaque objet PartyEndpoint se voit également attribuer par PlayFab Party un identificateur unique de point de terminaison de 16 bits qui vous permet de référencer ce point de terminaison spécifique dans les charges utiles des messages envoyés vers ou depuis d’autres objets PartyEndpoint du réseau. Cela offre par exemple un moyen pratique d’éviter la surcharge liée à l’envoi d’une chaîne complète et plus longue d’ID d’entité d’utilisateur ou d’un autre identificateur qu’il pourrait représenter, sans avoir à concevoir votre propre négociation d’accord d’identité pair à pair. Les objets PartyLocalEndpoint sont créés à l’aide de l’objet PartyNetwork qui les contient. Cette création entraîne la création des objets PartyEndpoint correspondants sur les appareils distants. Un point de terminaison peut être détruit explicitement par son créateur, ou est détruit implicitement lorsque l’appareil propriétaire se déconnecte du réseau ou que l’objet PartyLocalUser associé (s’il en a été spécifié un) est retiré du réseau.

​

Contrôle de clavardage

Les objets PartyChatControl sont le mécanisme permettant d’utiliser les fonctionnalités facultatives de communication par clavardage de PlayFab Party. Ils représentent les périphériques d’entrée/sortie audio, les préférences et les stratégies de communication associés à un utilisateur particulier. Le sous-objet spécialisé PartyLocalChatControl est également disponible pour les contrôles de clavardage créés par l’instance de jeu locale. C’est là que vous configurez les autorisations permettant la communication par clavardage vers ou depuis des objets PartyChatControl distants, par exemple pour choisir entre un clavardage à l’échelle du réseau et un clavardage limité à l’équipe, ou pour appliquer des restrictions liées à la stratégie de la plateforme. Les contrôles de clavardage locaux sont utilisés pour envoyer du texte de clavardage, synthétiser du texte en parole, demander des transcriptions et des traductions de flux vocaux, mettre en sourdine, et plus encore. Les objets PartyLocalChatControl doivent être connectés à un réseau avant d’être créés en tant qu’objets PartyChatControl sur les appareils distants de ce même réseau. Un appareil ne voit toujours qu’un seul objet PartyChatControl représentatif créé, même lorsque cet appareil et le contrôle de clavardage sont connectés à plusieurs réseaux en commun. Cela permet d’éviter une duplication ou une interruption inutile des messages de clavardage audio et textuel. Les objets PartyLocalChatControl sont créés à l’aide de l’objet PartyLocalDevice qui les contient. Un contrôle de clavardage peut être détruit explicitement par son créateur, ou est détruit implicitement lorsque l’appareil propriétaire se déconnecte du réseau ou que l’objet PartyLocalUser associé est retiré du réseau.

​

Changement d’état

Les structures PartyStateChange sont utilisées pour informer le jeu de toutes les fins d’opérations asynchrones, des messages entrants, des notifications de mise à jour et des autres événements liés à l’API. Pour simplifier la gestion d’interactions complexes entre plusieurs machines sur Internet, avec une synchronisation imprévisible, PlayFab Party garantit qu’il ne modifiera aucun état qu’il signale au moyen de l’API, sauf à la suite d’un appel explicite du jeu. Mais comme vous avez tout de même besoin d’un moyen de prendre connaissance des opérations initiées à distance ou des événements imprévus qui modifient l’état local, PlayFab Party et le jeu coopèrent au moyen d’une paire de méthodes spéciales, PartyManager::StartProcessingStateChanges() et PartyManager::FinishProcessingStateChanges(). Celles-ci sont appelées à un point de la boucle de travail du jeu où il est pratique de traiter ces mises à jour. Les nouveaux événements sont signalés par PartyManager::StartProcessingStateChanges() sous la forme d’un tableau de zéro ou plusieurs structures PartyStateChange. Une fois que le jeu a traité les changements d’état, le tableau est retourné à l’aide de PartyManager::FinishProcessingStateChanges(). La structure PartyStateChange n’est pas un objet complet en soi. Il s’agit d’un en-tête de base à convertir en une structure plus détaillée contenant des informations sur le type spécifique de fin d’opération ou de notification, des pointeurs vers les objets concernés et toute information d’erreur. L’utilisation des changements d’état est décrite en détail dans une rubrique ultérieure.

​

Étapes suivantes

• En savoir plus sur les invitations PlayFab Party et le modèle de sécurité
• Découvrir comment PlayFab Party interagit avec vos flux de découverte
• En savoir plus sur la communication par clavardage de PlayFab Party
• Découvrir comment utiliser les opérations asynchrones et les notifications dans PlayFab Party