PlayFab: Partyobjekte und ihre Beziehungen

Die erfolgreiche Nutzung der Leistungsfähigkeit und Flexibilität der PlayFab Party-API beginnt mit dem Verständnis der folgenden wichtigen Objekte, die in ihrem Bereich definiert sind:

• Gerät – Eine bestimmte Instanz des Spiels, die auf einem physischen Gerät ausgeführt wird. Immer, wenn die API verwendet wird, ist ein lokales Gerät vorhanden.
• Benutzer: Ein einzelner angemeldeter Spieler, oder genauer gesagt, eine PlayFab-Entitättitle_player_account, die das Spiel PlayFab Party zu Authentifizierungs- und Identifikationszwecken zur Verfügung stellt. Mindestens ein Benutzer ist mit einem bestimmten Gerät verknüpft.
• Netzwerk – Eine geschützte Sammlung von einem oder mehreren Geräten und deren autorisierten Benutzern, die das Spiel für den Austausch von Chats oder Datenkommunikation erstellt. Ein Netzwerk ist in der Regel auf das Konzept einer Multiplayer-Sitzung oder eines Chatpartys eines Spiels abgestimmt.
• Endpunkt – Eine Abstraktion zum Senden und Empfangen von Daten innerhalb eines Netzwerks. Ein Endpunkt kann ein Gerät, einen Benutzer oder ein beliebiges spielspezifisches Konzept darstellen.
• Chat-Steuerung – Eine Darstellung eines Benutzers, die speziell zum Konfigurieren, Generieren und Ausrichten von Sprach- und Textchats in einem oder mehreren Netzwerken dient.

Objektbeziehungen

Als vereinfachte konzeptionelle Hierarchie enthalten NetzwerkeGeräte, die wiederum Benutzer, optionale Endpunkte und optionale Chat-Steuerelemente enthalten. Beispiel:

Obwohl es einfach zu verstehen ist, ist das obige Beziehungsdiagramm tatsächlich eine unvollständige Darstellung der Fähigkeiten von PlayFab Party und kann irreführend sein, wenn es allein betrachtet wird. In Wirklichkeit unterstützt die Party-API Geräte, die eine Verbindung mit mehreren Netzwerken gleichzeitig herstellen. Zum Beispiel könnte man die Kommunikation mit einer Gruppe von Freunden im Laufe der Zeit aufrechterhalten wollen, da dieselbe Gruppe auch an separaten größeren Spielsitzungen mit Fremden teilnimmt und diese verlässt. Die Betrachtung dieses breiteren Szenarios ermöglicht es uns, die Beziehungen zwischen diesen Objekten besser zu verstehen.

Es mag intuitiv erscheinen, sich ein Gerät als zu Netzwerken gehörig vorzustellen, aber das ist nicht der Fall. Es ist richtiger zu wissen, dass Geräte an Netzwerken teilnehmen . Daher erstellt die Party-Bibliothek nur dann ein einzelnes Geräte-API-Objekt, egal ob remote oder lokal, wenn eine bestimmte Instance auftritt, unabhängig von der Anzahl der Netzwerke, die sie mit Ihrem lokalen Gerät teilt.

Das folgende Diagramm zeigt beispielsweise zwei Netzwerke und drei Geräte mit Benutzern, Chat-Steuerelementen und Endpunkten. Gerät A und seine beiden Chatsteuerelemente (mit zugeordneten Benutzern) nehmen an Netzwerk 1 teil, während die Geräte B und C sowohl mit Netzwerk 1als auch mit Netzwerk 2 mit jeweils einem einzigen Chatsteuerelement (und einem zugeordneten Benutzer) verbunden sind. Alle Geräte haben in jedem Netzwerk, in dem sie verbunden sind, einen oder zwei Endpunkte erstellt:

Im Diagramm sieht jedes Gerät eine einzelne Instance aller drei Geräte und ihrer Chat-Steuerelemente, da sie mindestens ein Netzwerk gemeinsam haben. Gerät A kennt nur die Endpunkte 1-4 in Netzwerk 1, aber die Geräte B und C können die Endpunkte 5-7 sehen, die sie in Netzwerk 2 erstellt haben.

Wenn Gerät C stattdessen nur an Netzwerk 2 und nicht an beiden Netzwerken teilnimmt, gilt Folgendes:

• Gerät C ist offensichtlich nicht in der Lage, Endpunkt 4 in Netzwerk 1 zu erstellen und auch nicht die Endpunkte 1-3 anzuzeigen.
• Gerät C weiß nichts über Gerät A oder seine beiden Chat-Steuerelemente, nur in Netzwerk 1.
• Gerät A würde Gerät C oder seine Chatsteuerung nur in Netzwerk 2 ebenfalls nicht sehen.

Gerät Bwürde jedoch weiterhin alle Geräte und ihre Chat-Steuerelemente sehen, da es sich weiterhin in beiden Netzwerken befindet.

Obwohl sich Geräte und Chatsteuerungen "außerhalb" einer strikten hierarchischen Strukturbeziehung mit Netzwerken befinden, ist es wichtig zu beachten, dass eine Spiel-Instance niemals auf ein Remotegerät oder eine Chatsteuerung ohne den Kontext eines zugehörigen Netzwerks trifft. Wenn das lokale und das Remotegerät oder die Chatsteuerung mindestens ein Netzwerk gemeinsam haben, ist das Remoteobjekt möglicherweise sichtbar. Wenn jedoch keine gemeinsamen Netzwerke vorhanden sind, wird das Remoteobjekt nie erstellt.

Allgemeine Objektattribute

Alle Objekte haben klar definierte Lebensdauern. Eine lokale Spiel-Instance erstellt und zerstört jedes Objekt direkt oder unter Verwendung standardisierter Benachrichtigungsmechanismen, die nur während eines Zeitfensters Ihrer Wahl signalisiert werden. Das Arbeiten mit Benachrichtigungen wird in einem späteren Thema ausführlicher beschrieben.

Alle PlayFab Party-API-Objekte unterstützen auch das Konzept eines benutzerdefinierten Kontexts, der einfach eine Möglichkeit ist, einen optionalen, nur lokal gültigen "Verknüpfungszeiger" oder -wert mit dem Objekt zu speichern. Benutzerdefinierte Kontexte erleichtern den Wechsel von PlayFab Party-Objekten zurück zu Ihren entsprechenden privaten Spielobjekten im Speicher (falls vorhanden), ohne dass eine ineffiziente Suche durchgeführt werden muss. Diese Werte werden nicht remote übertragen, da Zeigerwerte nur für die lokale Spiel-instance von Bedeutung sind.

Schließlich verfügen alle oben genannten Objekte mit Ausnahme des Netzwerks über ein spezialisiertes Unterobjekt "Local", das Methoden und Eigenschaften enthält, die nur dem lokalen Gerät zur Verfügung stehen, das das Objekt besitzt.

Beispielsweise gibt es ein Basisobjekt PartyEndpoint , das verwendet wird, um einen lokalen oder Remoteendpunkt darzustellen, und ein spezifischeres PartyLocalEndpoint Objekt, über PartyEndpoint::GetLocal() das nur abgerufen werden kann, wenn dieser Endpunkt tatsächlich vom lokalen Gerät erstellt wurde. Hier wird die PartyLocalEndpoint::SendMessage() Methode zum Übertragen von Spieldaten offengelegt, da es für ein Gerät nicht sinnvoll wäre, irgendwie Daten von den Quellendpunkten eines anderen Remotegeräts zu übertragen.

Bei Verwendung der C++ PlayFab Party-Schnittstelle (empfohlen) werden Objekte als C++-Klasseninstanzen verfügbar gemacht. Bei Verwendung der flachen C-Schnittstelle werden Objekte durch Handle-Werte dargestellt.

Die Rollen aller wichtigen Objekte im Detail

1. Manager (PartyManager)
2. Netzwerk (PartyNetwork)
3. Gerät (PartyDevice und PartyLocalDevice)
4. Benutzer (Benutzerentitäts-IDs und PartyLocalUser)
5. Endpunkt (PartyEndpoint und PartyLocalEndpoint)
6. Chat-Steuerung (PartyChatControl und PartyLocalChatControl)
7. Statusänderung (PartyStateChange)

Manager

Zusätzlich zu den zuvor zusammengefassten Objekten macht die PlayFab Party-API auch ein Singleton-Objekt der obersten Ebene PartyManager verfügbar.

Dieses Hilfs-/Organisationsobjekt wird weitgehend als Ausgangspunkt verwendet, um mit den anderen Objekten zu arbeiten. Mit dem Manager werden beispielsweise neue Netzwerke und lokale Benutzer erstellt. Alle asynchronen Vorgangsabschlüsse und Benachrichtigungen werden hier ebenfalls zentralisiert. Im Wesentlichen ist der Manager der Ort, an dem die PlayFab Party-Bibliothek selbst vor der Verwendung initialisiert und bereinigt wird, wenn sie nicht mehr benötigt wird.

Netzwerk

Ein PartyNetwork Objekt stellt eine geschützte Sammlung der teilnehmenden Geräte, ihrer autorisierten Benutzer und aller zugehörigen Endpunkte oder Chat-Steuerelemente dar. Netzwerke werden anfänglich leer erstellt, aber Geräte stellen eine Verbindung mit ihnen her und authentifizieren mindestens einen lokalen Benutzer im Netzwerk. Netzwerke ohne authentifizierte Benutzer werden nach einem Timeout automatisch zerstört.

Um eine Verbindung mit ihnen herzustellen, werden Netzwerke mithilfe von Netzwerkdeskriptoren referenziert. Netzwerkdeskriptoren sind weitgehend undurchsichtige binäre Strukturen, die die Informationen enthalten, die PlayFab Party intern benötigt, um das Netzwerk zu identifizieren und zu lokalisieren. Die API bietet Methoden zum Serialisieren der Strukturen in webdienstfreundliche Zeichenfolgen und zurück, sodass sie mit anderen Geräten ausgetauscht werden können, indem gängige Einladungsmechanismen für soziale Plattformen, PlayFab Matchmaking oder andere externe Rendezvous-Mechanismen außerhalb des Bereichs von PlayFab Party selbst verwendet werden.

Selbst mit einem Netzwerkdeskriptor ist der Zugriff auf ein Netzwerk auf autorisierte Benutzer beschränkt. Diese Benutzerberechtigung erfolgt während der Netzwerkerstellung und durch das anschließende Erstellen und Widerrufen von Einladungen, wie im Thema Einladungen und Sicherheitsmodell näher beschrieben.

Spiele können Einladungen verwenden, um den Zugang nur auf Freunde von Benutzern zu beschränken oder um zu verhindern, dass böswillige Spieler dem Netzwerk beitreten.

Geräte können mit mehreren Netzwerken gleichzeitig eine Verbindung herstellen. Weitere Informationen darüber, ob und wie Sie mehrere Netzwerke verwenden, finden Sie in einem späteren Thema.

Zu den Aktionen, die für PartyNetwork Objekte ausgeführt werden können, gehören die Authentifizierung lokaler Benutzer, das Verbinden und Auflisten von Chatsteuerelementen, das Erstellen und Aufzählen von Endpunkten oder das Abrufen von netzwerkweiten Leistungsinformationen.

Gerät

Das PartyDevice Objekt stellt eine bestimmte Instance des Spiels und seines PlayFab Party-Bibliothekscodes dar, der auf einem physischen Gerät ausgeführt wird. Die meisten Vorgänge werden nicht für PartyDevice Objekte selbst ausgeführt. Sie sind vielmehr ein organisatorischer Mechanismus zum Definieren, welche Endpunkte oder Chat-Steuerelemente zu dieser Spiel-instance gehören, insbesondere für Plattformen und Spiele, die mehr als einen lokalen Benutzer gleichzeitig unterstützen. PlayFab Party verwendet dieses Beziehungswissen, um die Übertragung von Spieldaten und Chat zu optimieren, indem nur eine Kopie einer Nachricht gesendet wird, selbst wenn sie beispielsweise von mehreren Zielen auf dem Gerät empfangen werden muss.

Remoteobjekte PartyDevice sind "Nebenprodukte" der Verbindung mit einem Netzwerk und der Authentifizierung eines Benutzers in diesem Netzwerk. Sie werden nur erstellt, wenn gültige, authentifizierte Remotebenutzer, die dem Gerät zugeordnet sind, an einem Netzwerk teilnehmen, mit dem das lokale Gerät ebenfalls verbunden ist. Dementsprechend werden sie auch zerstört, wenn das nicht mehr stimmt.

Andererseits ist das PartyLocalDevice spezialisierte Unterobjekt immer verfügbar, sodass die lokale Spiel-Instance darauf verweisen kann, solange PlayFab Party initialisiert ist. Sie wird nie explizit erstellt oder zerstört.

Benutzer

Ein PlayFab Party-Benutzer ist ein eindeutiger menschlicher Spieler, für den das Spiel eine PlayFab-Spieleranmeldung durchführt, um eine Entitäts-ID und ein title_player_account Token abzurufen.

Remotebenutzer werden innerhalb der PlayFab Party-API ausschließlich durch ihre Entitäts-ID-Zeichenfolge identifiziert, die Chat-Steuerelementen und optional Endpunkten zugeordnet ist. Sie werden nicht mit einem dedizierten Objekt dargestellt. Dies liegt daran, dass PlayFab Party außer zur unformatierten Identifizierung und als Label, das diesen anderen Objekten zugeordnet ist, nicht über Funktionen verfügt, die sinnvoll mit beliebigen Benutzern interagieren.

Umgekehrt gibt es für lokale Benutzer explizite PartyLocalUser Objekte, da Spiele die Verwaltung ihres Lebens innerhalb von PlayFab Party besitzen. Das Spiel erstellt in der Regel eine Registerkarte PartyLocalUser , wenn das Spiel diesen PlayFab-Spieler erfolgreich mit der entsprechenden Anmeldemethode angemeldet hat, und zerstört die PartyLocalUser Anzeige gegebenenfalls, wenn sich der Benutzer abmeldet. Für Plattformen und Spiele, die mehrere lokale angemeldete Spieler unterstützen, sollten zusätzliche PartyLocalUser Objekte für jeden Spieler erstellt werden.

PartyLocalUser Objekte sind auch deshalb wichtig, weil sie die Grundlage aller Authentifizierungen bilden. Ein gültiger lokaler Benutzer muss vorhanden sein, um entweder ein neues Netzwerk zu erstellen oder sich bei einem zu authentifizieren.

Das Autorisieren von Benutzern wird im Thema " Einladungen und das Sicherheitsmodell" ausführlicher beschrieben.

Fast jeder Vorgang erfordert, dass ein bereitgestellt wird oder vorhanden PartyLocalUser ist, obwohl nur sehr wenige Operationen an PartyLocalUser Objekten selbst ausgeführt werden.

PartyLocalUser Objekte werden mit dem PartyManager Objekt erstellt. Sie können nur von ihren Schöpfern explizit zerstört werden. Obwohl sie keine direkte Objektdarstellung auf Remotegeräten haben, werden Chat-Steuerelemente und ihnen zugeordnete Endpunkte zerstört, wenn das besitzende Gerät das PartyLocalUser Netzwerk entfernt oder vom Netzwerk trennt, ordnungsgemäß oder auf andere Weise.

Endpunkt

PartyEndpoint Objekte sind optional, bilden jedoch den Kern der PlayFab-Party-Datenkommunikation für Spiele, die sie nutzen. Wie typische Netzwerksockets sind Endpunkte ein abstrahierter Adressierungsmechanismus für die Herkunft oder Ausrichtung von Datennachrichten innerhalb eines Netzwerks. Dabei kann es sich um ein Gerät, einen einzelnen Benutzer oder ein beliebiges im Spiel definiertes Konzept (z. B. eine Panzereinheit) handeln, das Sie für das Senden und Empfangen von Nachrichten eindeutig identifizieren möchten.

Das spezialisierte PartyLocalEndpoint Unterobjekt ist für Endpunkte vorgesehen, die von der lokalen Spiel-instance im Netzwerk erstellt wurden. Hier befindet sich die meiste Endpunktfunktionalität . Es PartyLocalEndpoint::SendMessage() überträgt Spieldatennutzlasten vom PartyLocalEndpoint an ein oder mehrere andere PartyEndpoint Objekte im selben Netzwerk. Sie bietet verschiedene Optionen für die Auswahl, wie der Verlust von Internetpaketen am besten gehandhabt werden soll (z. B. garantierte Lieferung und/oder Bestellung), um den Kompromiss zwischen niedriger Latenz und der Zusammenführung mehrerer Nachrichten von demselben oder anderen lokalen Endpunkten für eine geringere Bandbreitennutzung zu kontrollieren und zu reagieren, wenn die Verbindungsqualität nicht ausreicht, um die Senderate des Spiels zu unterstützen.

Jedem PartyEndpoint Objekt ist nicht nur Quelle oder Ziel für Datennachrichten, sondern auch ein eindeutiger 16-Bit-Endpunktbezeichner von PlayFab Party zugewiesen, mit dem Sie auf den spezifischen Endpunkt in Nachrichtennutzlasten verweisen können, die an oder von separaten PartyEndpoint Objekten innerhalb des Netzwerks gesendet werden. Dies bietet eine bequeme Möglichkeit, den Aufwand für das Senden einer vollständigen, größeren Benutzerentitäts-ID-Zeichenfolge oder eines anderen Bezeichners, den sie darstellen könnte, zu vermeiden, ohne eine eigene Peer-to-Peer-Identitätsvereinbarung aushandeln zu müssen.

PartyLocalEndpoint Objekte werden mit ihrem enthaltenden PartyNetwork Objekt erstellt. Dies führt dazu, dass entsprechende PartyEndpoint Objekte auf Remote-Geräten erstellt werden. Ein Endpunkt kann explizit von seinem Ersteller zerstört werden oder wird implizit zerstört, wenn das besitzerführende Gerät vom Netzwerk getrennt wird oder das zugeordnete PartyLocalUser Objekt (falls eines angegeben wurde) aus dem Netzwerk entfernt wird.

Chat-Steuerung

PartyChatControl Objekte sind der Mechanismus für die Verwendung der optionalen Chat-Kommunikationsfeatures von PlayFab Party. Sie repräsentieren die zugeordneten Audioeingabe-/Ausgabegeräte, Einstellungen und Kommunikationsrichtlinien eines bestimmten Benutzers.

Das spezialisierte PartyLocalChatControl Unterobjekt ist auch für Chat-Steuerelemente verfügbar, die von der lokalen Spiel-instance erstellt werden. Hier konfigurieren Sie die Berechtigungen, die die Chatkommunikation zu oder von Remoteobjekten PartyChatControl ermöglichen, z. B. um einen netzwerkweiten statt einen reinen Teamchat auszuwählen oder um Einschränkungen der Plattformrichtlinie anzuwenden. Lokale Chat-Steuerelemente werden zum Senden von Chattext, Synthetisieren von Text-zu-Sprache, Anfordern von Transkriptionen und Übersetzungen von Sprachströmen, Stummschalten und mehr verwendet.

PartyLocalChatControl Objekte müssen mit einem Netzwerk verbunden sein, bevor sie als PartyChatControl Objekte auf Remotegeräten in demselben Netzwerk erstellt werden. Auf einem Gerät wird immer nur ein einzelnes repräsentatives PartyChatControl Objekt erstellt, auch wenn dieses Gerät und die Chatsteuerung mit mehreren gemeinsamen Netzwerken verbunden sind. Dadurch können unnötige Duplikate oder Unterbrechungen von Audio- und Textchatnachrichten vermieden werden.

PartyLocalChatControl Objekte werden mit dem enthaltenden PartyLocalDevice Objekt erstellt. Ein Chatsteuerelement kann explizit von seinem Ersteller zerstört werden oder wird implizit zerstört, wenn das besitzerführende Gerät vom Netzwerk getrennt wird oder das zugehörige PartyLocalUser Objekt aus dem Netzwerk entfernt wird.

Statusänderung

PartyStateChange Strukturen werden verwendet, um das Spiel über alle asynchronen Vorgangsabschlüsse, eingehenden Nachrichten, Updatebenachrichtigungen und andere API-bezogene Ereignisse zu informieren.

Um Ihre Arbeit mit komplexen Interaktionen mehrerer Computer über das Internet mit unvorhersehbarem Timing zu vereinfachen, garantiert PlayFab Party, dass keine Zustände geändert werden, die es von der API meldet, es sei denn, es handelt sich um einen expliziten Aufruf durch das Spiel. Da Sie jedoch immer noch eine Möglichkeit benötigen, sich über remote initiierte Vorgänge oder ungeplante Ereignisse zu informieren, die den lokalen Zustand ändern, arbeiten PlayFab Party und das Spiel durch ein spezielles Methodenpaar zusammen. PartyManager::StartProcessingStateChanges()PartyManager::FinishProcessingStateChanges() Diese werden an einem Punkt in der Arbeitsschleife des Spiels aufgerufen, an dem es zweckmäßig ist, solche Updates zu handhaben. Die neuen Ereignisse werden als PartyManager::StartProcessingStateChanges() Array von null oder mehr PartyStateChange Strukturen gemeldet. Sobald das Spiel die Zustandsänderungen verarbeitet hat, wird das Array mit PartyManager::FinishProcessingStateChanges()zurückgegeben.

Die PartyStateChange Struktur selbst ist kein vollständiges Objekt. Es handelt sich um eine Basiskopfzeile, die in eine detailliertere Struktur umgewandelt wird, die Informationen über den spezifischen Fertigstellungs- oder Benachrichtigungstyp, Verweise auf die relevanten Objekte und Fehlerinformationen enthält.

Die Arbeit mit Zustandsänderungen wird in einem späteren Thema ausführlich beschrieben.

Nächste Schritte

• Informationen zu PlayFab-Partyeinladungen und dem Sicherheitsmodell
• Erfahren Sie, wie PlayFab Party mit Ihren Ermittlungsabläufen interagiert
• Erfahren Sie mehr über PlayFab Party-Chatkommunikation
• Erfahren Sie, wie Sie mit asynchronen Vorgängen und Benachrichtigungen in PlayFab Party arbeiten