Schnellstart für Partys
In dieser Schnellstartanleitung werden die Kernfunktionen von PlayFab Party zusammen mit Codeausschnitten beschrieben. PlayFab Party ist von Grund auf plattformübergreifend konzipiert. Wir haben diese Schnellstarts auf die gleiche Weise strukturiert, wobei die meisten Informationen für alle Plattformen gelten und plattformspezifische Voraussetzungen und Schritte in den verknüpften Dokumenten beschrieben werden.
Ein tieferes Verständnis finden Sie in der verknüpften Referenz und der konzeptionellen Dokumentation sowie plattformspezifischen Beispielanwendungen.
Notiz
In dieser Schnellstartanleitung wird die Verwendung des C++-Party-SDK behandelt.
- Informationen für Unity-Benutzer finden Sie in der Schnellstartanleitung für Unity.
- Informationen Unreal Engine Benutzer, die das PlayFab Online-Subsystem für Unreal Engine verwenden möchten, finden Sie unter Schnellstart für Unreal.
Voraussetzungen
Sie benötigen ein PlayFab-Konto, und Sie müssen das Party-Feature aktivieren , um party zu verwenden.
- Erstellen Sie Ihr PlayFab-Konto, oder melden Sie sich bei ihr an. Anweisungen finden Sie unter Schnellstart: Game Manager.
- Aktivieren Sie das Party-Feature über Game Manager über Ihr PlayFab-Konto.
Plattformvoraussetzungen
Bevor Sie mit dieser Schnellstartanleitung beginnen, führen Sie alle erforderlichen plattformspezifischen Setups aus, wie in den folgenden Themen angegeben:
Wenn Sie die plattformspezifischen Schritte abgeschlossen haben, fahren Sie mit den restlichen Schritten in diesem Thema fort, um die PlayFab-Party einzurichten.
Herunterladen und Einrichten des Party SDK
Es gibt Party-SDKs für verschiedene Plattformen und Spiele-Engines. Wählen Sie die gewünschte Option aus, und laden Sie es herunter. Downloadlinks finden Sie unter Party SDKs.
Nach der Installation des SDK sollten Sie ein Beispiel ausführen, um zu sehen, wie Party funktioniert, bevor Sie mit dem Schreiben von Code beginnen. Um ein Beispiel herunterzuladen, wechseln Sie zu Partybeispiele.
Wenn Sie Party in Xbox- und PC-Titeln verwenden, empfiehlt es sich, die Party Xbox Live Helper Library zu verwenden, um konsistente Funktionen und Verhaltensweisen sicherzustellen. Diese Bibliothek hilft Ihrem Titel, die Xbox Live-Anforderungen zu erfüllen. Weitere Informationen finden Sie unter Xbox-Anforderungen.
Melden Sie sich bei Ihrem PlayFab-Titel an, und rufen Sie ein Entitätstoken und eine Entitäts-ID ab.
Zum Initialisieren und Verwenden von Party müssen Sie sich bei PlayFab anmelden. Sie können PlayFabClientAPI::LoginWithCustomID oder eine plattformspezifische Anmeldemethode verwenden.
Nachdem Sie die Anmeldung ausgeführt haben, gibt PlayFab eine Entitäts-ID und ein Entitätstoken als Teil von LoginResult zurück. Diese beiden wichtigsten Informationen werden verwendet, um einen lokalen Benutzer instance für PlayFab Party zu initialisieren.
Ein Beispiel für die Anmeldung mit einer benutzerdefinierten ID, wie sie in implementiert ist PlayFabManager.cpp , ist in diesem Codeausschnitt dargestellt:
PlayFabClientAPI::LoginWithCustomID(
loginRequest,
[this, callback, userId](const LoginResult& loginResult, void*)
{
// Sign in was successful.
DEBUGLOG("PlayFab::signin -- Login with custom id callback\n");
// Save the PlayFab id and entity data for Party authentication.
m_playfabId = loginResult.PlayFabId;
if (loginResult.EntityToken.notNull() && loginResult.EntityToken->Entity.notNull())
{
m_entityKey = loginResult.EntityToken->Entity;
m_entityToken = loginResult.EntityToken->EntityToken;
}
Nachdem Sie die Entitäts-ID und das Entitätstoken von PlayFab erfolgreich abgerufen haben, können Sie mit dem Aktivieren und anschließenden Initialisieren von Party fortfahren.
Notiz
Wenn Sie Xbox Live verwenden, können Sie sich auch über die Party Xbox Live Helper Library anmelden.
Initialisieren der PlayFab-Party
Auf hoher Ebene umfasst das Initialisieren der Partei die folgenden Schritte:
- Rufen Sie einen Singletonverweis auf ab,
PartyManagerund initialisieren Sie ihn.
Dies ist die primäre Verwaltungsklasse für die Interaktion mit der Parteibibliothek.
auto& partyManager = PartyManager::GetSingleton();
PartyError err;
//Only initialize the party manager once.
if (m_partyInitialized == false)
{
// Initialize PlayFab Party
err = partyManager.Initialize(titleId);
if (PARTY_FAILED(err))
{
DEBUGLOG("Initialize failed: %s\n", GetErrorMessage(err));
return;
}
m_partyInitialized = true;
}
- Erstellen Sie ein lokales Benutzerobjekt.
Dieses lokale Benutzerobjekt wird verwendet, um einen lokalen Benutzer auf dem Gerät (PC, Konsole, Telefon, ...) darzustellen, wenn Netzwerk- und Chatvorgänge ausgeführt werden. Das lokale Benutzerobjekt wird mit der PlayFab-Entitäts-ID initialisiert.
//Only create a local user object if it doesn't exist.
if (m_localUser == nullptr)
{
PartyString entityId = Managers::Get<PlayFabManager>()->EntityId().c_str();
PartyString entityToken = Managers::Get<PlayFabManager>()->EntityToken().c_str();
// Create a local user object
err = partyManager.CreateLocalUser(
entityId, // User id
entityToken, // User entity token
&m_localUser // OUT local user object
);
if (PARTY_FAILED(err))
{
DEBUGLOG("CreateLocalUser failed: %s\n", GetErrorMessage(err));
return;
}
}
- Erstellen Sie ein Chat-Steuerelement, und legen Sie den Audioeingangs- und Ausgabekanal fest, in dem der Partei Daten empfängt oder weiterleitet.
Das Chatsteuerungsobjekt verwaltet die Chatvorgänge für den Benutzer auf dem jeweiligen Gerät.
// Only create local chat controls if they don't exist.
if (m_localChatControl == nullptr)
{
PartyLocalDevice* localDevice = nullptr;
// Retrieve the local device
err = partyManager.GetLocalDevice(&localDevice);
if (PARTY_FAILED(err))
{
DEBUGLOG("GetLocalDevice failed: %s\n", GetErrorMessage(err));
return;
}
// Create a chat control for the local user on the local device
err = localDevice->CreateChatControl(
m_localUser, // Local user object
m_languageCode, // Language id
nullptr, // Async identifier
&m_localChatControl // OUT local chat control
);
if (PARTY_FAILED(err))
{
DEBUGLOG("CreateChatControl failed: %s\n", GetErrorMessage(err));
return;
}
// Use system default settings for the audio input device
err = m_localChatControl->SetAudioInput(
PartyAudioDeviceSelectionType::SystemDefault, // Selection type
nullptr, // Device id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetAudioInput failed: %s\n", GetErrorMessage(err));
return;
}
// Use system default settings for the audio output device
err = m_localChatControl->SetAudioOutput(
PartyAudioDeviceSelectionType::SystemDefault, // Selection type
nullptr, // Device id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetAudioOutput failed: %s\n", GetErrorMessage(err));
}
- Legen Sie die Transkriptions- und Übersetzungsoptionen fest.
Transkription und Übersetzung sind optionale Chatfunktionen, die die Barrierefreiheit Ihres Spiels erheblich verbessern können. Weitere Informationen zu diesen Features finden Sie in der Chatübersicht.
// Get the available list of text to speech profiles
err = m_localChatControl->PopulateAvailableTextToSpeechProfiles(nullptr);
if (PARTY_FAILED(err))
{
DEBUGLOG("Populating available TextToSpeechProfiles failed: %s \n", GetErrorMessage(err));
}
// Set transcription options for transcribing other users regardless of language, and ourselves.
PartyVoiceChatTranscriptionOptions transcriptionOptions =
PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithMatchingLanguages |
PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithNonMatchingLanguages |
PartyVoiceChatTranscriptionOptions::TranslateToLocalLanguage |
PartyVoiceChatTranscriptionOptions::TranscribeSelf;
// Set the transcription options on our chat control.
err = m_localChatControl->SetTranscriptionOptions(
transcriptionOptions, // Transcription options
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetTranscriptionOptions failed: %s\n", GetErrorMessage(err));
}
// Enable translation to local language in chat controls.
err = m_localChatControl->SetTextChatOptions(
PartyTextChatOptions::TranslateToLocalLanguage,
nullptr
);
An diesem Punkt haben Sie die PlayFab-Party in Ihrer Anwendung oder Ihrem Spiel initialisiert.
Ein vollständiges NetworkManager::Initialize() Beispiel finden Sie im Code in NetworkManager.cpp in der Demo-App.
Der nächste Schritt besteht darin, ein Parteinetzwerk zu erstellen und eine Verbindung damit herzustellen.
Erstellen eines Partynetzwerks
Ein Party-Netzwerk ist eine gesicherte Sammlung von einem oder mehreren Geräten und deren autorisierten Benutzern, die das Spiel erstellt, um Chat- oder Datenkommunikation auszutauschen. Ein Partynetzwerk richtet sich in der Regel nach dem Konzept einer Multiplayer-Sitzung oder eines Chats aus. Sie können Nachrichten nur an Spieler in Ihrem eigenen Netzwerk senden.
Der folgende Codeausschnitt zeigt, wie wir ein Parteinetzwerk erstellen können.
// Initialize an empty network descriptor to hold the result of the following call.
PartyNetworkDescriptor networkDescriptor = {};
// Create a new network descriptor
err = PartyManager::GetSingleton().CreateNewNetwork(
m_localUser, // Local User
&cfg, // Network Config
0, // Region List Count
nullptr, // Region List
&invitationConfiguration, // Invitation configuration
nullptr, // Async Identifier
&networkDescriptor, // OUT network descriptor
nullptr // applied initialinvitationidentifier.
);
Sobald der Funktionsaufruf von CreateNewNetwork() erfolgreich ist, wird ein Netzwerkdeskriptor-PartyNetworkDescriptor-Objekt zurückgegeben/aufgefüllt. Der Deskriptor enthält die Daten, die für andere Spieler erforderlich sind, um eine Verbindung mit einem Netzwerk herzustellen.
Informationen zu den anderen Funktionsparametern finden Sie in der API-Referenzdokumentation .
Nachdem ein Parteinetzwerk erstellt wurde, werden Einladungen verwendet, um zu steuern, welche Benutzer dem Netzwerk beitreten können. PlayFab Matchmaking, PlayFab Lobby, Plattformseinladungen oder benutzerdefinierte Spieledienste können verwendet werden, um Verbindungsdetails mit anderen Spielern zu teilen.
Der einfachste Einladungstyp ist eine offene Einladung, die aus einem Netzwerkdeskriptor besteht. Ausführliche Informationen zu allen Einladungstypen und zum Sicherheitsmodell finden Sie unter Einladungen und das Sicherheitsmodell.
Netzwerkdeskriptor der Freigabepartei
An diesem Punkt haben Sie einen Party-Netzwerkdeskriptor und sind bereit, ihn mit anderen Spielern zu teilen. Es gibt viele Synchronisierungsmechanismen, die Sie verwenden können, um diese Informationen zu teilen, aber zu schnellen Testzwecken können Sie die Netzwerkbeschreibung Party aus der Host party-Sitzung manuell kopieren und in die Gastparteisitzung einfügen. Wir empfehlen die Verwendung von PlayFab Lobby, um den Netzwerkdeskriptor in Ihrem Multiplayer-Spiel freizugeben, aber Sie können auch Ihren eigenen Lobbydienst, Einladungen oder andere Freigabemechanismen basierend auf den Anforderungen Ihres Spiels verwenden.
Netzwerkdeskriptor der Partei manuell freigeben
Verwenden Sie in der Hostsitzung PartyManager::SerializeNetworkDescriptor(), um den Netzwerkdeskriptor in eine Zeichenfolge zu serialisieren und in der Konsole auszugeben.
Kopieren Sie die Netzwerkdeskriptorzeichenfolge, und fügen Sie sie lokal oder remote in ein anderes Spiel ein.
Verwenden Sie in der Gastsitzung PartyManager::D eserializeNetworkDescriptor(), um den Netzwerkdeskriptor aus der Netzwerkdeskriptorzeichenfolge zu deserialisieren.
Stellen Sie eine Verbindung mit dem Party-Netzwerk her.
Verwenden der PlayFab-Lobby zum Freigeben des Party-Netzwerkdeskriptors
PlayFab Lobby kann verwendet werden, um Spieler vorübergehend zu gruppieren, wenn sie in und aus Spielen wechseln, und kann verwendet werden, um den Netzwerkdeskriptor zu synchronisieren, sodass Spieler demselben Netzwerk beitreten können. PlayFab Lobby ist hochgradig anpassbar, um eine Vielzahl von Gameplay-Anforderungen auf allen unterstützten Plattformen und plattformübergreifend zu unterstützen. Weitere Informationen zur Verwendung von PlayFab Lobby mit Echtzeitbenachrichtigungen finden Sie im Multiplayer SDK-Schnellstart .
Ausführliche Informationen zur Verwendung von PlayFab Lobby zusammen mit PlayFab Party finden Sie unter Erstellen einer Lobby mit dem PlayFab Multiplayer SDK.
Herstellen einer Verbindung mit einem Parteinetzwerk
Führen Sie die folgenden Schritte aus, um dem Partynetzwerk beizutreten, nachdem Sie die Netzwerkbeschreibung "Party" abgerufen haben:
Verwenden Sie PartyManager::D eserializeNetworkDescriptor(), um den Netzwerkdeskriptor aus der Netzwerkdeskriptorzeichenfolge zu deserialisieren.
Stellen Sie eine Verbindung mit dem Party-Netzwerk her.
Authentifizieren Sie den lokalen Benutzer für das Netzwerk.
Verbinden Sie das lokale Chat-Steuerelement mit dem Netzwerk, damit wir VOIP verwenden können.
Richten Sie einen Party Network-Endpunkt für den Nachrichtendatenverkehr des Spiels ein.
PartyNetworkDescriptor networkDescriptor = {};
// Deserialize the remote network's descriptor
PartyError err = PartyManager::DeserializeNetworkDescriptor(descriptor, &networkDescriptor);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed to deserialize descriptor: %s\n", GetErrorMessage(err));
errorCallback(err);
return;
}
// This portion of connecting to the network is the same for
// both creating a new and joining an existing network.
PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
&descriptor, // Network descriptor
nullptr, // Async identifier
&m_network // OUT network
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Authenticate the local user on the network so we can participate in it
err = m_network->AuthenticateLocalUser(
m_localUser, // Local user
networkId, // Invitation Id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Connect the local user chat control to the network so we can use VOIP
err = m_network->ConnectChatControl(
m_localChatControl, // Local chat control
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Establish a network endoint for game message traffic
err = m_network->CreateEndpoint(
m_localUser, // Local user
0, // Property Count
nullptr, // Property name keys
nullptr, // Property Values
nullptr, // Async identifier
&m_localEndpoint // OUT local endpoint
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
Senden einer Nachricht an ein anderes Netzwerkgerät oder -endpunkt
Nachdem Sie eine Verbindung mit dem Party-Netzwerk hergestellt haben, können Sie eine Nachricht mithilfe des lokalen Endpunktobjekts senden.
if (m_localEndpoint && m_state == NetworkManagerState::NetworkConnected)
{
auto packet = message.Serialize();
// Form the data packet into a data buffer structure
PartyDataBuffer data[] = {
{
static_cast<const void*>(packet.data()),
static_cast<uint32_t>(packet.size())
},
};
// Set delivery options for guaranteed and sequential delivery.
PartySendMessageOptions deliveryOptions =
PartySendMessageOptions::GuaranteedDelivery |
PartySendMessageOptions::SequentialDelivery;
// Send out the message to all other peers
PartyError err = m_localEndpoint->SendMessage(
0, // endpoint count; 0 = broadcast
nullptr, // endpoint list
deliveryOptions, // send message options
nullptr, // configuration
1, // buffer count
data, // buffer
nullptr // async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to SendMessage: %s\n", GetErrorMessage(err));
}
}
Der vollständige Code ist in NetworkManager.cpp verfügbar.
Empfangen einer Nachricht und Rendern auf dem lokalen Gerät
Der letzte Schritt besteht darin, nachrichten zu empfangen, die von Mitgliedern der Remotepartei gesendet wurden, und deren Wiedergabe auf Ihrem Gerät.
Wichtig
Beim Erstellen des Chat-Steuerelements in einem der vorherigen Schritte haben Sie bereits die Audioeingabe- und -ausgabegeräte eingerichtet, die von der Partei zum Senden, Empfangen und Rendern von Audiodaten verwendet werden. Um die Audionachrichten zu empfangen, müssen Sie auch die entsprechende Chatberechtigung zwischen den einzelnen Chatsteuerelementen festlegen, wenn Audiodaten fließen sollen. Standardmäßig sind die Chatberechtigungen auf NONE festgelegt. Weitere Informationen finden Sie im Artikel Chatberechtigungen .
Die Verarbeitung anderer Nachrichten von der Parteiebene erfolgt am besten in einem dedizierten Updatethread oder einer hochfrequenten Spielschleife. Die Spielschleife sollte so eingerichtet werden, dass jeder Frame ausgeführt wird und nachrichten vom Party-Manager über die Funktion StartProcessingStateChanges() empfangen werden.
Eine vollständige Beschreibung aller Zustandsänderungen finden Sie in der Dokumentation zur Parteienreferenz. Alternativ können Sie auf die NetworkManager.cpp verweisen, um ein Beispiel für die Verarbeitung der einzelnen Zustandsänderungen zu erhalten.
Behandeln des Anhaltens von Titeln
Einige Plattformen unterstützen das vorübergehende Anhalten der Ausführung Ihres Titels: iOS, Switch und GDK. Wenn Ihr Titel angehalten wird, wird der Netzwerkstapel ungültig, und PlayFab Party kann keine Verbindung mit dem PlayFab Party-Netzwerk aufrechterhalten. Besondere Überlegungen sind erforderlich, um das Anhalten und Fortsetzen der Ausführung Ihres Titels bei verwendung von PlayFab Party zu behandeln.
iOS
Unter iOS müssen Sie das Netzwerk der PlayFab-Party verlassen und erneut eine Verbindung mit dem Netzwerk herstellen.
Um das Party-Netzwerk zu verlassen, rufen Sie LeaveNetwork() auf. Nachdem das Netzwerk reaktiviert wurde, rufen Sie ConnectToNetwork() mit dem vorherigen Party-Netzwerkdeskriptor auf.
Switch und GDK
Auf Nintendo Switch und Microsoft GDK müssen Sie playFab Party sauber und warten, bis die Titelausführung fortgesetzt wird, bevor Sie playFab Party erneut initialisieren und erneut eine Verbindung mit Ihrem Netzwerk herstellen.
Rufen Sie Cleanup() auf, um die Partei zu beenden.
Wichtig
Der Aufruf von Cleanup() gibt alle Bibliotheksressourcen zurück und zerstört alle Bibliotheksobjekte. Nach der erneuten Initialisierung von Party müssen Sie alle Bibliotheksobjekte wie lokale Benutzer und Chatsteuerelemente neu erstellen und alle vorherigen Netzwerkzustände wiederherzustellen, indem Sie lokale Benutzer erneut authentifizieren, Chatsteuerelemente erneut verbinden und Endpunkte neu erstellen.
Rufen Sie initialize() auf, nachdem das Netzwerk reaktiviert wurde. Nachdem die Partei erfolgreich initialisiert wurde, sind die folgenden Schritte erforderlich, um erneut einem vorherigen PlayFab Party Network beizutreten:
Stellen Sie mit dem vorherigen Party-Netzwerkdeskriptor eine Verbindung mit dem Party-Netzwerk her.
Erstellen Sie alle lokalen Benutzerobjekte neu, und authentifizieren Sie diese lokalen Benutzer erneut im Netzwerk.
Erstellen Sie alle lokalen Chatsteuerelemente neu, und verbinden Sie diese Chatsteuerelemente erneut mit dem Netzwerk, um VOIP zu aktivieren.
Erstellen Sie alle Party Network-Endpunkte für den Spielnachrichtendatenverkehr neu.
PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
&descriptor, // Network descriptor
nullptr, // Async identifier
&m_network // OUT network
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Authenticate the local user on the network so we can participate in it
err = m_network->AuthenticateLocalUser(
m_localUser, // Local user
networkId, // Invitation Id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Connect the local user chat control to the network so we can use VOIP
err = m_network->ConnectChatControl(
m_localChatControl, // Local chat control
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Establish a network endoint for game message traffic
err = m_network->CreateEndpoint(
m_localUser, // Local user
0, // Property Count
nullptr, // Property name keys
nullptr, // Property Values
nullptr, // Async identifier
&m_localEndpoint // OUT local endpoint
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
Wichtig
Wenn die erneute Verbindung erfolgreich abgeschlossen wurde, kann die Partei nun mit anderen Peers kommunizieren. Wenn das vorherige Netzwerk jedoch nicht mehr vorhanden ist, tritt bei der erneuten Verbindung ein Fehler auf. In diesem Fall sollten Sie den entsprechenden Verbindungsfehler behandeln.
Weitere Schritte
Weitere Informationen zu PlayFab Party-Objekten und ihren Beziehungen finden Sie in der Referenzdokumentation zur Party-API , damit Ihr Spiel diese Funktionen optimal nutzen kann.
Weitere Xbox-spezifische Anleitungen finden Sie in den Xbox-Anforderungen .
Weitere Informationen
- Partyfeatures
- Party-SDKs
- Partybeispiele
- Multiplayer-Dienste
- Partyobjekte und ihre Beziehungen
- Grundlagen des Partychats
- Party-Einladungen und das Sicherheitsmodell
- Partei interagiert mit Ihren Ermittlungsflows
- Referenzdokumentation zur Party-API
- Richtlinien für die Benutzeroberfläche von Parteien für Sprachsynthese und Spracherkennung