Xbox-Anforderungen
Wenn Ihr Spiel auf Xbox-Konsolen ausgerichtet ist, muss es eine Reihe von Anforderungen erfüllen, um eine konsistente Funktionalität und ein konsistentes Verhalten bei der Interaktion mit Xbox Live sicherzustellen. Dieser Satz von Anforderungen ist in den Xbox-Anforderungen (kurz XRs) aufgeführt. XRs interagieren und überlappen sich mit den Richtlinien , die erforderlich sind, um Xbox Live in Ihrem Spiel auf dem PC und anderen Plattformen zu verwenden. Hier werden bewährte Methoden für PlayFab Party beschrieben, mit denen Sie diese Anforderungen erfüllen können.
Eine Kurzübersicht finden Sie in der folgenden Tabelle, in der PlayFab Party-Szenarien mit den XRs übereinstimmen, die sie adressieren:
PlayFab Party Xbox Live Helper-Bibliothek
Neben der Zentralen PlayFab Party-Bibliothek bieten wir eine Xbox Live Helper-Bibliothek an, die zur Einhaltung von Xbox Live-Richtlinien und erweiterten XRs entwickelt wurde. Die Verwendung dieser Hilfsbibliothek ist nicht erforderlich, wird aber dringend empfohlen und als bewährte Methode angesehen. Die hier vorgestellten Beispiele setzen die Verwendung der Xbox Live-Hilfsbibliothek voraus.
Ausrichten der PlayFab-Party an den Chateinstellungen und -berechtigungen eines Xbox Live-Benutzers
PlayFab Party verwendet ein Opt-in-Modell für die Chatkommunikation und schränkt standardmäßig die gesamte Kommunikation zwischen zwei Chatsteuerelementen auf den Satz von Kommunikationen ein, die beide Teilnehmer aktiviert haben. Weitere Informationen finden Sie in der Dokumentation zu Chatberechtigungen und Stummschaltung.
Die Xbox Live Helper-Bibliothek der PlayFab-Party gibt an, welche Chatberechtigungen aktiviert werden sollen, damit sie den Einstellungen und Berechtigungen der Xbox Live-Benutzer entsprechen, die derzeit in der Partysitzung kommunizieren. Weitere Informationen finden Sie in der Dokumentation zum Respektieren der Datenschutzeinstellungen und -berechtigungen eines Xbox Live-Benutzers.
Durch die ordnungsgemäße Nutzung der PlayFab Party und der Xbox Live Helper-Bibliothek kann Ihr Spiel die von XR-015 festgelegten Anforderungen vollständig erfüllen und die relevanten Kommunikationsanforderungen von XR-045 erfüllen. Weitere Anforderungen außerhalb des Geltungsbereichs der PlayFab-Party finden Sie in der technischen Dokumentation zu XR-045 .
Verwalten eines Multiplayer-Sitzungsdokuments
PlayFab Party bietet keine Xbox-Benutzerliste. Es basiert darauf, dass Ihr Spiel den Multiplayer Session Directory Service (MPSD) verwendet, um eine Liste zu verwalten und party-Netzwerkaktivitäten den Benutzern in der Spielsitzung zuzuordnen. PlayFab Party kündigt Remoteendpunkte und Chatsteuerelemente an, wenn sie aus Partynetzwerken kommen und gehen. Die diesen Objekten zugeordneten PlayFab-Entitäts-IDs sollten mit den Xbox-Benutzern im MPSD-Dokument abgeglichen werden, um zu erkennen, welche PlayFab Party-Objekte Xbox-Benutzer in der Spielsitzung darstellen. Bei Crossplay-Szenarien kann eine PlayFab-Entität, die nicht einem Xbox-Benutzer zugeordnet ist, einen Benutzer in einem anderen Multiplayer-Ökosystem darstellen.
Um Xbox-Benutzer zu erkennen, sollten Sie Zuordnungen zwischen PlayFab-Entitäts-IDs und Xbox Live-Benutzern erstellen. Um dies zu erreichen, wird empfohlen, die Liste der Xbox Live-Benutzer der Sitzung in einem MPSD-Dokument zu speichern und diese Xbox Live-Benutzer mithilfe der Xbox Live-Hilfsbibliothek in PlayFab-Entitäts-IDs zu übersetzen. Beispiele finden Sie unter Zuordnung zwischen Xbox Live-Benutzer-IDs und PlayFab-Entitäts-IDs.
Zusätzlich zur Bereitstellung der Liste des Partynetzwerks ermöglichen MPSD-Dokumente auch viele Multiplayer-Umgebungen im Xbox Multiplayer-Ökosystem wie Matchmaking, Plattformeinladungen, Aktuelle Spielerlisten und Mitmachen. Weitere Informationen zum Integrieren von Parteinetzwerken in diese MPSD-Flows finden Sie unter Verwenden von PlayFab-Party mit MPSD.
Weitere Informationen finden Sie unter ÜBERSICHT ÜBER MPSD.
Wichtig
Dieser Abschnitt enthält bewährte Methoden für die Verwendung von PlayFab Party zusammen mit MPSD, aber PlayFab Party selbst erfüllt nicht implizit die MPSD-Anforderungen von XR-067. Informationen zur Erfüllung dieser Anforderungen finden Sie in der technischen Dokumentation zu XR-067 .
Verwenden von Xbox-Clients in Crossplay-Partynetzwerken
Beachten Sie für Crossplay-Szenarien die folgenden bewährten Methoden bei der Interaktion mit dem Xbox Live-Ökosystem.
Wichtig
Dieser Abschnitt enthält bewährte Methoden für die Verwendung von PlayFab Party in Crossplay-Szenarien mit Xbox Live, aber die Verwendung von PlayFab Party erfüllt nicht implizit die Crossplay-Anforderungen von XR-007. Informationen zur Erfüllung dieser Anforderungen finden Sie in der technischen Dokumentation zu XR-007 .
Identifizieren von Spielern in einer netzwerkübergreifenden Spielsitzung
Eindeutige Spieler sollten über Multiplayer-Ökosysteme hinweg identifizierbar und unterscheidbar sein. Zu diesem Zweck stellt PlayFab Party PlayFab-Entitäts-IDs für die verschiedenen Objekte bereit, die Benutzern in Ihrer Sitzung zugeordnet sein können: PartyLocalUser, PartyEndpoint, PartyChatControl.
Netzwerkübergreifende Anzeigenamen werden von der PlayFab-Party-API nicht bereitgestellt. Wenn Sie Xbox-Benutzer auf der Benutzeroberfläche anzeigen, sollten Sie deren Gamertag verwenden, und das Gamertag sollte aus der Xbox-Benutzer-ID im MPSD-Dokument aufgelöst werden. Nicht-Xbox-Benutzer sollten auf der Benutzeroberfläche basierend auf den Richtlinien in XR-007 angezeigt werden. Wenn kein plattformseitig bereitgestellter Anzeigename vorhanden ist, bietet PlayFab Unterstützung für Anzeigenamen über GetPlayerProfile. Wenn sie einem Netzwerk beitreten, sollte ein Spieler seinen Anzeigenamen in einem freigegebenen Sitzungsdokument veröffentlichen, damit andere Spieler sehen können.
Obwohl die PlayFab Party-Bibliothek einige ihrer Objekte PlayFab-Benutzern zuordnet (über PlayFab-Entitäts-IDs), bietet die Bibliothek keine Funktionen zum Identifizieren der Multiplayer-Ökosysteme, denen ein PlayFab-Benutzer zugeordnet sein könnte. Um Xbox Live PlayFab-Benutzer von Benutzern in anderen Multiplayer-Ökosystemen zu unterscheiden, wird empfohlen, auf die PlayFab-Entitäts-IDs in einem Partynetzwerk mit MPSD zu verweisen. Weitere Informationen zum Unterscheiden von Xbox Live-Spielern von Nicht-Xbox Live-Spielern über MPSD finden Sie im Abschnitt verwalten einer Multiplayer-Sitzung.
Weitere Informationen zu den Anforderungen zum Identifizieren von Benutzern in Crossplay-Netzwerken mit Xbox Live finden Sie unter XR-007.
Berücksichtigen von Berechtigungen für die netzwerkübergreifende Kommunikation für Xbox Live-Benutzer
PlayFab Party erfüllt nicht implizit die Einschränkungen für die netzwerkübergreifende Kommunikation von Xbox Live. Daher bietet die PlayFab Party Xbox Live Helper-Bibliothek Funktionen zum Abfragen der Netzwerkkommunikationsberechtigungen eines Xbox Live-Benutzers. Sie müssen diese Informationen verwenden, um die in XR-007 angegebenen Anforderungen für die netzwerkübergreifende Kommunikation zu erfüllen.
Weitere Informationen finden Sie unter Respektieren der netzwerkübergreifenden Kommunikation .
Verwenden Sie PlayFab Party-Einladungen, um den Zugriff auf Netzwerke einzuschränken, wenn Crossplay nicht zulässig ist.
Xbox Live-Benutzer benötigen netzwerkübergreifende Berechtigungen, um mit Nicht-Xbox Live-Benutzern in netzwerkübergreifenden Spielsitzungen zu interagieren. Die PlayFab-Partei hält diese netzwerkübergreifenden Einschränkungen (wie in XR-007 beschrieben) nicht implizit ein, daher muss diese Berechtigung außerhalb der PlayFab-Partybibliothek abgefragt werden. Wenn diese Berechtigungen nicht erteilt werden, sollten Sie das Partynetzwerk so einschränken, dass nur die Xbox Live-Benutzer zugelassen werden, die im MPSD-Dokument der Spielsitzung bekannt sind. Sie können dies erreichen, indem Sie unseren Beispielablauf zur Teilnahme an der Bearbeitung erweitern, um Partyeinladungen zu verwenden, die es nur bekannten Xbox-Benutzern ermöglichen, dem Netzwerk beizutreten.
Stellen Sie zunächst sicher, dass das Parteinetzwerk mit einer eingeschränkten Einladung erstellt wird.
PartyString networkCreatorEntityId;
RETURN_VOID_IF_FAILED(m_localPartyUser->GetEntityId(&networkCreatorEntityId));
PartyInvitationConfiguration newNetworkInitialInvite{};
newNetworkInitialInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity
newNetworkInitialInvite.revocability = PartyInvitationRevocability::Anyone; // the initial invitation must be revocable by anyone
// this initial invitation only allows the original xbl user creating the network
newNetworkInitialInvite.entityIdCount = 1;
newNetworkInitialInvite.entityIds = &networkCreatorEntityId;
PartyError error = PartyManager::GetSingleton().CreateNewNetwork(
m_localPartyUser,
&networkConfiguration,
0,
nullptr,
&newNetworkInitialInvite,
nullptr,
nullptr,
nullptr);
Wenn ein neuer Xbox-Benutzer dem Netzwerk beitreten möchte, fügt er sich dem Sitzungsdokument ähnlich wie beim Join-in-Progress-Flow zunächst selbst hinzu. Wenn der Spieler, der sie in das Netzwerk zulassen möchte, das Update sieht, aktualisiert er den Satz von Einladungen, um das Sitzungsdokument widerzuspiegeln. Dadurch wird sichergestellt, dass nur Benutzer im Sitzungsdokument (die garantiert Xbox Live-Benutzer sind) dem Netzwerk beitreten können.
void
OnSessionDocumentUpdated(
PartyNetwork* network,
uint32_t usersInDocumentCount,
const uint64_t* usersInDocument
)
{
PartyInvitationConfiguration newInvite{};
newInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity
newInvite.revocability = PartyInvitationRevocability::Creator; // must be revocable by the creator only
// the updated invite should contain all users currently in the document
std::vector<PartyString> entityIdsInDocument;
for (uint32_t i = 0; i < usersInDocumentCount; ++i)
{
uint64_t xboxUserId = usersInDocument[i];
// Call title-defined xuid->entityid mapping helper
PartyString xboxUserEntityId = GetEntityIdFromXboxUserId(xboxUserId);
if (xboxUserEntityId != nullptr)
{
entityIdsInDocument.push_back(xboxUserEntityId);
}
else
{
DEBUGLOG("User %llu did not have a matching entity ID.", xboxUserId);
}
}
newInvite.entityIdCount = entityIdsInDocument.size();
newInvite.entityIds = entityIdsInDocument.data();
// Create a new invitation which includes all of the users currently in the document
PartyInvitation* newInvitation;
PartyError error = network->CreateInvitation(
m_localUser,
&newInvite,
nullptr,
&newInvitation);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::CreateInvitation failed! (error=0x%x)", network, error);
return;
}
// Post the invitation's id somewhere that it can be seen by anyone trying to join/rejoin
PostInvitationToMPSD(newInvite);
// Cleanup previous invitations. This isn't strictly necessary, but is a good practice.
uint32_t invitationCount;
PartyInvitationArray invitations;
error = network->GetInvitations(&invitationCount, &invitations);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::GetInvitations failed! (error=0x%x)", network, error);
return;
}
for (uint32_t i = 0; i < invitationCount; ++i)
{
if (invitations[i] == newInvite)
{
continue; // don't prune the old invitation
}
PartyInvitation* oldInvitation = invitations[i];
error = network->RevokeInvitation(m_localUser, oldInvitation, nullptr);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::RevokeInvitation failed! (err=0x%x)", network, error);
}
}
}
Notiz
Da Sie zwischen Xbox Live-Benutzer-IDs und PlayFab-Entitäts-IDs übersetzen müssen, wird empfohlen, eine Zuordnung zwischen den beiden zu erstellen. Beispiele dazu finden Sie unter Zuordnung zwischen Xbox Live-Benutzer-IDs und PlayFab-Entitäts-IDs .
Synchronisieren der Xbox Live-Profileinstellungen
PlayFab Party entspricht standardmäßig den Profileinstellungen in XR-048. Die Bibliothek behält keinen permanenten Cache von Xbox Live-Profileinstellungen bei. Wenn Profileinstellungen für die Verwendung von PlayFab Party benötigt werden, werden die Einstellungen von Xbox Live abgefragt und bleiben für die Lebensdauer des der Einstellung zugeordneten PlayFab Party-API-Objekts gültig, werden aber nicht über mehrere Instanzen des Objekts hinweg beibehalten.
Informationen zur Verwendung von Xbox Live-Profileinstellungsdaten außerhalb der PlayFab Party finden Sie in der technischen Dokumentation zu XR-048 .
Unterstützen von Plattform-Multiplayer-Joinflows
Auf Xbox können Spieler multiplayer-Spiele über die Features "Mitmachen" und "Plattformeinladung" beitreten. PlayFab Party lässt sich nicht direkt in diese Plattformfeatures integrieren, unterstützt aber deren Verwendung über PartyNetworkDescriptor - und PartyInvitation -Objekte.
PartyNetworkDescriptor -Objekte stellen die Verbindungsinformationen bereit, die für einen Remotebenutzer zum Suchen und Herstellen einer Verbindung mit dem Party-Netzwerk erforderlich sind, und können über PartyManager::SerializeNetworkDescriptorserialisiert werden.
PartyInvitation -Objekte stellen Remotebenutzern eine ID zur Verfügung, die zum Authentifizieren bei einem Parteinetzwerk und zum Beitritt zu einem Parteinetzwerk verwendet wird. Um Remotebenutzern die Teilnahme an Multiplayer-Spielen über Join-in-Progress- und Plattformeinladungen zu ermöglichen, integrieren Sie den serialisierten Netzwerkdeskriptor und die Partyeinladungs-ID in Ihre bereits vorhandenen Flows. Beispielflows finden Sie auch im Dokument Using PlayFab Party with MPSD (Verwenden von PlayFab-Party mit MPSD ).
Weitere Informationen zu den Anforderungen für Plattform-Multiplayer-Joinflows finden Sie in der technischen Dokumentation zu XR-064 und XR-124 .
Freundeslisten
Obwohl PlayFab Party nicht nativ mit Freundeslisten auf einer Plattform interagiert, müssen Multiplayer-Spiele möglicherweise dennoch Freundeslisten für verschiedene Szenarien berücksichtigen. Informationen zu Anforderungen und Anleitungen bei der Interaktion mit Xbox Live und netzwerkübergreifenden Freundeslisten finden Sie in der folgenden Dokumentation:
- Anforderungen an die Xbox Live-Freundesliste (XR-070)
- Anforderungen an die netzwerkübergreifende Freundesliste (XR-007)
- Xbox Social Manager
- Xbox Live Services-API (XSAPI)
Berücksichtigen der Wiederholungsrichtlinie für den Xbox Live-Dienst und einschränkungen des Dienstzugriffs.
Die PlayFab-Party interagiert nicht direkt mit Xbox Live-Diensten außerhalb der Xbox Live-Hilfsbibliothek. Die Xbox Live Helper-Bibliothek entspricht intern den Wiederholungsrichtlinien und Zugriffsbeschränkungen für ihre relevanten Xbox Live-Dienste, wie in XR-074 und XR-132 beschrieben. Darüber hinaus können Sie API-Fehler als Ergebnis der Einhaltung dieser Dienstrichtlinien erkennen, indem Sie die folgenden Fehlercodes verwenden, die von der Xbox Live-Hilfsbibliothek gemeldet werden: PartyXblChatPermissionMaskReason::XboxLiveServiceError und PartyXblStateChangeResult::P artyServiceError.
Weitere Informationen zur Einhaltung dieser Dienstrichtlinien außerhalb der Xbox Live-Hilfsbibliothek finden Sie in der technischen Dokumentation zu XR-074 und XR-132 .