PlayFab Party-Objekte 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 Umfang definiert sind:

• Gerät : Eine eindeutige Instanz des Spiels, das auf einem physischen Gerät ausgeführt wird. Ein lokales Gerät ist immer vorhanden, wenn die API verwendet wird.
• Benutzer: Ein einzelner angemeldeter Spieler oder genauer gesagt eine PlayFab-Entitättitle_player_account, die das Spiel playFab Party zu Authentifizierungs- und Identifikationszwecken bereitstellt. Einem bestimmten Gerät sind mindestens ein Benutzer zugeordnet.
• Netzwerk : Eine gesicherte 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 entspricht in der Regel dem Konzept einer Multiplayer-Sitzung oder einer Chatparty eines Spiels.
• 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.
• Chatsteuerung : Eine Darstellung eines Benutzers, der speziell für die Konfiguration, den Ursprung und die Ausrichtung von Sprach- und Textchats in einem oder mehreren Netzwerken verwendet.

Objektbeziehungen

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

Das obige Beziehungsdiagramm ist zwar einfach genug zu verstehen, ist aber tatsächlich eine unvollständige Darstellung der Funktionen von PlayFab Party und kann irreführend sein, wenn es von sich aus genommen wird. In Wirklichkeit unterstützt die Party-API Geräte, die gleichzeitig eine Verbindung mit mehreren Netzwerken herstellen. Beispielsweise könnte man die Kommunikation mit einer Gruppe von Freunden im Laufe der Zeit aufrechterhalten möchten, da dieselbe Gruppe auch beitritt und separate größere Spielsitzungen mit Fremden verlässt. Wenn wir dieses umfassendere Szenario betrachten, können wir die Beziehungen zwischen diesen Objekten besser verstehen.

Es mag intuitiv sein, ein Gerät als netzwerkgehörig zu betrachten, aber dies ist nicht der Fall. Es ist richtiger zu erkennen, dass Geräte an Netzwerken teilnehmen . Daher erstellt die Parteibibliothek immer nur ein einzelnes Geräte-API-Objekt, unabhängig davon, wie viele Netzwerke sie für Ihr lokales Gerät gemeinsam mit Ihrem lokalen Gerät verwendet, wenn eine bestimmte Instanz gefunden wird.

Das folgende Diagramm zeigt beispielsweise zwei Netzwerke und drei Geräte mit Benutzern, Chatsteuerelementen und Endpunkten. Gerät A und seine beiden Chatsteuerelemente (mit zugeordneten Benutzern) sind an Netzwerk 1 beteiligt, während Geräte B und C sowohl mit Netzwerk 1 als auch mit Netzwerk 2 mit jeweils einem einzigen Chat-Steuerelement (und dem 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 Instanz aller drei Geräte und deren Chatsteuerelemente, da sie über mindestens ein gemeinsames Netzwerk verfügen. Gerät A kennt nur die Endpunkte 1 bis 4 in Netzwerk 1, geräte B und C können jedoch auch 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, dann:

• Gerät C wäre offensichtlich nicht in der Lage, Endpunkt 4 in Netzwerk 1 zu erstellen, und die Endpunkte 1-3 werden nicht angezeigt.
• Gerät C kann nur in Netzwerk 1 keine Informationen zu Gerät A oder den beiden zugehörigen Chatsteuerelementen haben.
• Gerät A würde auf ähnliche Weise Gerät C oder seine Chatsteuerung nur in Netzwerk 2 nicht sehen.

Gerät Bwürde jedoch weiterhin alle Geräte und deren Chatsteuerelemente sehen, da es sich noch in beiden Netzwerken befindet.

Obwohl Geräte und Chatsteuerelemente "außerhalb" einer strengen hierarchischen Strukturbeziehung mit Netzwerken sind, ist es wichtig zu beachten, dass eine Spielinstanz niemals tatsächlich auf ein Remotegerät oder eine Chatsteuerung trifft, ohne den Kontext eines begleitenden Netzwerks. Wenn das lokale und das Remotegerät oder die Chatsteuerung mindestens ein Gemeinsames Netzwerk haben, ist das Remoteobjekt möglicherweise sichtbar. Wenn jedoch keine gemeinsamen Netzwerke vorhanden sind, wird das Remoteobjekt nie erstellt.

Notiz

Spiele müssen nicht gleichzeitig eine Verbindung mit mehreren Netzwerken herstellen, um playFab Party erfolgreich verwenden zu können. Weitere Informationen dazu, ob und wie Mehrere Netzwerke verwendet werden, finden Sie in einem nachfolgenden erweiterten Thema.

Allgemeine Objektattribute

Alle Objekte haben eine klar definierte Lebensdauer. Eine lokale Spielinstanz erstellt und zerstört jedes Objekt direkt oder mithilfe standardisierter Benachrichtigungsmechanismen, die nur während eines Zeitfensters der Spielauswahl 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 verfügbaren Verknüpfungszeiger oder -wert mit dem Objekt zu speichern. Benutzerdefinierte Kontexte erleichtern das Zurückwechseln von PlayFab Party-Objekten zu ihren entsprechenden privaten Spielobjekten im Arbeitsspeicher (falls vorhanden), ohne dass eine ineffiziente Suche durchgeführt werden muss. Diese Werte werden nicht remote übertragen, da Zeigerwerte nur für die lokale Spielinstanz Bedeutung haben.

Schließlich verfügen alle oben genannten Objekte mit Ausnahme des Netzwerks über ein spezialisiertes "Lokales" Unterobjekt, das Methoden und Eigenschaften enthält, die nur für das lokale Gerät verfügbar sind, das das Objekt besitzt.

Beispielsweise gibt es ein Basisobjekt PartyEndpoint , das verwendet wird, um einen lokalen oder Remoteendpunkt darzustellen, und ein spezifischeres PartyLocalEndpoint Objekt, das nur über PartyEndpoint::GetLocal() abgerufen werden kann, wenn dieser Endpunkt tatsächlich vom lokalen Gerät erstellt wurde. Hier wird die PartyLocalEndpoint::SendMessage() Methode zum Übertragen von Spieldaten verfügbar gemacht, da es für ein Gerät nicht sinnvoll wäre, 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 Handlewerte dargestellt.

Die Rollen aller Hauptobjekte 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. Chatsteuerung (PartyChatControl und PartyLocalChatControl)
7. Zustandsänderung (PartyStateChange)

Manager

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

Dieses Hilfsprogramm-/Organisationsobjekt wird größtenteils als Ausgangspunkt für die Arbeit mit den anderen Objekten verwendet. In Tha Manager werden beispielsweise neue Netzwerke und lokale Benutzer erstellt. Alle asynchronen Vorgangsvervollständigungen und Benachrichtigungen werden hier ebenfalls zentralisiert. Im Grunde 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 gesicherte Sammlung teilnehmender Geräte, deren autorisierten Benutzer und alle zugehörigen Endpunkte oder Chatsteuerelemente dar. Netzwerke werden zunächst leer erstellt, aber Geräte stellen eine Verbindung 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, wird mithilfe von Netzwerkdeskriptoren auf Netzwerke verwiesen. 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 allgemeine Social Platform-Einladungsmechanismen, PlayFab Matchmaking oder andere externe Rendezvous-Mechanismen außerhalb des Bereichs von PlayFab Party selbst verwendet werden.

Notiz

Der Netzwerkdeskriptor für ein Netzwerk kann sich in seltenen Fällen ändern. Spiele sollten auf Benachrichtigungen über solche Änderungen vorbereitet werden und dann den neuen Netzwerkdeskriptor für ein vorhandenes Netzwerk aktualisieren oder erneut ankündigen, um Probleme mit der Verbindung zusätzlicher Geräte zu vermeiden.

Selbst bei einem Netzwerkdeskriptor ist der Zugriff auf ein Netzwerk auf autorisierte Benutzer beschränkt. Diese Benutzerautorisierung erfolgt während der Netzwerkerstellung und durch nachfolgende Erstellung und Widerruf von Einladungen, wie im Thema Einladungen und das Sicherheitsmodell ausführlicher beschrieben.

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

Geräte können gleichzeitig eine Verbindung mit mehreren Netzwerken herstellen. Weitere Informationen dazu, ob und wie Mehrere Netzwerke verwendet werden, finden Sie in einem späteren Thema.

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

Gerät

Das PartyDevice -Objekt stellt eine eindeutige Instanz des Spiels und dessen PlayFab Party-Bibliothekscode dar, der auf einem physischen Gerät ausgeführt wird. Die meisten Vorgänge werden nicht für PartyDevice Objekte selbst ausgeführt, sondern es handelt sich um einen Organisationsmechanismus zum Definieren, welche Endpunkte oder Chatsteuerelemente zu dieser Spielinstanz gehören, insbesondere für Plattformen und Spiele, die mehrere lokale Benutzer gleichzeitig unterstützen. PlayFab Party verwendet dieses Beziehungswissen, um die Übertragung von Spieldaten und Chats zu optimieren, indem nur eine Kopie einer Nachricht gesendet wird, auch wenn mehrere Ziele auf dem Gerät diese empfangen müssen, zum Beispiel.

Remoteobjekte PartyDevice sind "Nebenprodukte" des Herstellens einer 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. Entsprechend werden sie auch zerstört, wenn das nicht mehr wahr ist.

Andererseits ist das PartyLocalDevice spezialisierte Unterobjekt immer für die lokale Spielinstanz verfügbar, um darauf zu verweisen, solange PlayFab Party initialisiert ist. Sie wird niemals 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 zu erhalten.

Remotebenutzer werden innerhalb der PlayFab-Party-API nur anhand ihrer Entitäts-ID-Zeichenfolge identifiziert, die Chatsteuerelementen und optional endpunkten zugeordnet ist. Sie werden nicht mithilfe eines dedizierten Objekts dargestellt. Dies liegt daran, dass PlayFab Party keine Funktionalität aufweist, die sinnvoll mit beliebigen Benutzern interagiert, außer zur unformatierten Identifizierung und als Bezeichnung, die diesen anderen Objekten zugeordnet ist.

Umgekehrt gibt es für lokale Benutzer explizite PartyLocalUser Objekte, da Spiele die Verwaltung ihrer Lebensdauer innerhalb der PlayFab Party besitzen. Das Spiel erstellt in der Regel einen PartyLocalUser , wenn das Spiel erfolgreich den PlayFab-Spieler mit der entsprechenden Anmeldemethode protokolliert hat, und zerstört die nach Bedarf, wenn sich dieser PartyLocalUser Benutzer abmeldet. Für Plattformen und Spiele, die mehrere angemeldete lokale Spieler unterstützen, PartyLocalUser sollten zusätzliche Objekte für jeden Spieler erstellt werden.

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

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

Fast jeder Vorgang erfordert, dass ein PartyLocalUser bereitgestellt oder vorhanden ist, auch wenn nur sehr wenige Vorgänge für PartyLocalUser Objekte selbst ausgeführt werden.

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

Endpunkt

PartyEndpoint -Objekte sind optional, aber der Kern der PlayFab Party-Datenkommunikation für Spiele, die sie nutzen. Wie typische Netzwerksockets sind Endpunkte ein abstrahiertes Adressierungsmechanismus für die Ursprungs- oder Zieldatennachrichten in einem Netzwerk. Sie können ein Gerät, einen einzelnen Benutzer oder ein beliebiges spieldefiniertes Konzept (z. B. eine Tankeinheit) darstellen, das Sie zum Senden und Empfangen von Nachrichten eindeutig identifizieren möchten.

Das spezialisierte PartyLocalEndpoint Unterobjekt ist für Endpunkte vorgesehen, die im Netzwerk von der lokalen Spielinstanz erstellt werden. Hier befinden sich die meisten Endpunktfunktionen . Es PartyLocalEndpoint::SendMessage() überträgt Spieldatennutzlasten von an PartyLocalEndpoint ein oder mehrere andere PartyEndpoint Objekte im selben Netzwerk. Es bietet verschiedene Optionen für die Auswahl, wie der Verlust von Internetpaketen am besten behandelt werden soll (z. B. Garantie für die Übermittlung und/oder Reihenfolge), um den Kompromiss zwischen geringer Latenz und dem Zusammenfügen mehrerer Nachrichten von demselben oder anderen lokalen Endpunkten für eine geringere Bandbreitennutzung zu steuern und zu reagieren, wenn die Verbindungsqualität nicht ausreicht, um die Senderate des Spiels zu unterstützen. Weitere Informationen zum Übertragen von Spieldaten mithilfe von Endpunkten finden Sie in einem späteren Thema.

Jedes Objekt ist nicht nur eine Quelle oder ein Ziel für Datennachrichten selbst, es wird auch ein eindeutiger 16-Bit-Endpunktbezeichner von PlayFab Party zugewiesen, PartyEndpoint 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 Mehraufwand für das Senden einer vollständigen, größeren Benutzerentitäts-ID-Zeichenfolge oder eines anderen Bezeichners zu vermeiden, der z. B. dargestellt werden kann, ohne eine eigene Peer-zu-Peer-Identitätsvereinbarungsaushandlung erstellen zu müssen.

PartyLocalEndpoint -Objekte werden mit ihrem enthaltenden PartyNetwork Objekt erstellt. Dies führt dazu, dass entsprechende PartyEndpoint Objekte auf Remotegeräten erstellt werden. Ein Endpunkt kann vom Ersteller explizit zerstört werden oder wird implizit zerstört, wenn das besitzende Gerät die Verbindung mit dem Netzwerk trennt oder das zugeordnete PartyLocalUser Objekt (sofern angegeben) aus dem Netzwerk entfernt wird.

Chat-Steuerelement

PartyChatControl -Objekte sind der Mechanismus für die Verwendung der optionalen Chatkommunikationsfeatures von PlayFab Party. Sie stellen die einem bestimmten Benutzer zugeordneten Audioeingabe-/Ausgabegeräte, Einstellungen und Kommunikationsrichtlinien dar.

Das spezialisierte PartyLocalChatControl Unterobjekt ist auch für Chatsteuerelemente verfügbar, die von der lokalen Spielinstanz erstellt werden. Hier konfigurieren Sie die Berechtigungen, die die Chatkommunikation mit oder von Remoteobjekten PartyChatControl zulassen, z. B. zum Auswählen eines netzwerkweiten Chats im Vergleich zu teambasierten Chats oder zum Anwenden von Plattformrichtlinieneinschränkungen. Lokale Chatsteuerelemente werden verwendet, um Chattext zu senden, Text in Sprache zu synthetisieren, Transkriptionen und Übersetzungen von Sprachdatenströmen anzufordern, stummzuschalten und vieles mehr.

PartyLocalChatControl -Objekte müssen mit einem Netzwerk verbunden sein, bevor sie als PartyChatControl Objekte auf Remotegeräten im selben Netzwerk erstellt werden. Einem Gerät wird immer nur ein einziges repräsentatives PartyChatControl Objekt angezeigt, das erstellt wurde, auch wenn dieses Gerät und die Chatsteuerung mit mehreren gemeinsamen Netzwerken verbunden sind. Dies trägt dazu bei, unnötige Duplizierungen oder Unterbrechungen von Audio- und Textchatnachrichten zu vermeiden.

PartyLocalChatControl -Objekte werden mit dem enthaltenden PartyLocalDevice -Objekt erstellt. Ein Chat-Steuerelement kann vom Ersteller explizit zerstört werden oder wird implizit zerstört, wenn das besitzende Gerät die Verbindung mit dem Netzwerk trennt oder das zugeordnete PartyLocalUser Objekt aus dem Netzwerk entfernt wird.

Zustandsänderung

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

Um die Arbeit mit komplexen Interaktionen mit mehreren Computern über das Internet mit unvorhersehbarem Timing zu vereinfachen, garantiert PlayFab Party, dass es keinen Zustand ändert, der von der API gemeldet wird, außer als Folge eines expliziten Aufrufs durch das Spiel. Da Sie jedoch immer noch eine Möglichkeit benötigen, sich über remote initiierte Vorgänge oder ungeplante Vorkommen zu informieren, die den lokalen Zustand ändern, arbeiten PlayFab Party und das Spiel über ein spezielles Methodenpaar PartyManager::StartProcessingStateChanges() und PartyManager::FinishProcessingStateChanges()zusammen. Diese werden an einem Punkt in der Arbeitsschleife des Spiels aufgerufen, an dem es praktisch ist, solche Updates zu verarbeiten. Die neuen Ereignisse werden als PartyManager::StartProcessingStateChanges() Array von null oder mehr PartyStateChange Strukturen gemeldet. Sobald das Spiel die Zustandsänderungen behandelt hat, wird das Array mithilfe von PartyManager::FinishProcessingStateChanges()zurückgegeben.

Die PartyStateChange -Struktur ist selbst kein vollständiges Objekt. Es handelt sich um einen Basisheader, der in eine detailliertere Struktur umgewandelt werden soll, die Informationen zum bestimmten Typ der Vervollständigung oder Benachrichtigung, Zeiger auf die relevanten Objekte und Fehlerinformationen enthält.

Das Arbeiten mit Zustandsänderungen wird in einem späteren Thema ausführlich beschrieben.

Nächste Schritte

• Erfahren Sie mehr über PlayFab Party-Einladungen und das Sicherheitsmodell
• Erfahren Sie, wie PlayFab Party mit Ihren Ermittlungsflows interagiert.
• Erfahren Sie mehr über die Chatkommunikation von PlayFab Party
• Erfahren Sie, wie Sie mit asynchronen Vorgängen und Benachrichtigungen in playFab Party arbeiten.