Schnellstart: Win32
Erste Schritte mit dem PlayFab Services SDK für Win32. Führen Sie die folgenden Schritte aus, um die Bibliotheken in Ihr Projekt einzuschließen und den Beispielcode für die grundlegende PlayFab-Funktionalität auszuprobieren.
In dieser Schnellstartanleitung erfahren Sie, wie Sie Ihren ersten PlayFab-API-Aufruf mithilfe des Win32 SDK ausführen. Bevor Sie fortfahren, stellen Sie sicher, dass Sie die Schritte unter Schnellstart: Game Manager ausgeführt haben, um sicherzustellen, dass Sie über ein PlayFab-Konto verfügen und mit dem PlayFab-Spiel-Manager vertraut sind.
Voraussetzungen
- Ein PlayFab-Entwicklerkonto.
- Visual Studio 2022 installiert.
Projekteinrichtung
Laden Sie das PlayFab SDK von der Releaseseite des PlayFab SDK in Ihr Projekt herunter.
Importieren Sie PlayFabServicesSDK.Win32.props in Ihr Projekt. Sie können dies manuell in der Projektdatei tun oder indem Sie das Fenster Eigenschaften-Manager in Visual Studio öffnen, mit der rechten Maustaste auf das Projekt klicken und Vorhandenes Eigenschaftenblatt hinzufügen auswählen.
Problembehandlung
Wenn Sie Probleme beim Verknüpfen des SDK in Ihrem Projekt haben, müssen Sie möglicherweise 17.5-Buildtools und -Bibliotheken über die Visual Studio-Installer installieren. Klicken Sie für VS2022 auf Ändern , und installieren Sie diese beiden Komponenten.
Initialisieren und Anmelden
Header
Fügen Sie PFServices.h ein, um Zugriff auf alle enthaltenen PlayFab-Funktionen zu erhalten:
#include <playfab/services/PFServices.h>
Initialisierung
Für die PlayFab-Initialisierung sind zwei Funktionsaufrufe erforderlich: PFServicesInitialize und PFServiceConfigCreateHandle. Das Ergebnis dieser Initialisierung ist pfServiceConfigHandle. Sie stellen dieses Handle für einen nachfolgenden Anmeldeaufruf bereit und leiten den Aufruf an den richtigen Titel im PlayFab-Back-End weiter.
HRESULT hr = PFServicesInitialize(nullptr); // Add your own error handling when FAILED(hr) == true
PFServiceConfigHandle serviceConfigHandle{ nullptr };
hr = PFServiceConfigCreateHandle(
"https://ABCDEF.playfabapi.com", // PlayFab API endpoint - obtained in the Game Manager
"ABCDEF", // PlayFab Title id - obtained in the Game Manager
&serviceConfigHandle);
Anmelden
Sobald Sie über eine PFServiceConfigHandle verfügen, können Sie es verwenden, um einen Spieleranmeldeanruf zu tätigen. Verwenden Sie im SDK eine PFAuthenticationReLoginWith*Async-Methode wie PFAuthenticationLoginWithSteamAsync. Mit dieser Funktion können Sie sich mit einem SteamTicket bei PlayFab anmelden.
Nach dem Tätigen eines Anmeldeaufrufs können Sie die status des Anrufs mit XAsyncGetStatus überprüfen. Die status beginnt als E_PENDING und ändert sich in S_OK, nachdem der Aufruf erfolgreich abgeschlossen wurde. Wenn der Aufruf aus irgendeinem Grund fehlschlägt, spiegelt die status diesen Fehler wider. Die Fehlerbehandlung bei allen PlayFab Services-Aufrufen funktioniert auf diese Weise.
Zusammen mit einem S_OK Ergebnis erhalten Sie ein PFEntityHandle zurück. Sie verwenden dieses Handle, um nachfolgende PlayFab-Aufrufe als angemeldeter Spieler zu tätigen. Es enthält alle Materialien, die für die Authentifizierung beim PlayFab-Dienst als betreffenden Spieler erforderlich sind.
PFAuthenticationLoginWithSteamRequest request{};
request.createAccount = true;
request.steamTicket = steamTicket; // A ticket obtained from Steam
XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithSteamAsync(serviceConfigHandle, &request, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
std::vector<char> loginResultBuffer;
PFAuthenticationLoginResult const* loginResult;
size_t bufferSize;
hr = PFAuthenticationLoginWithSteamGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);
PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithSteamGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);
Dienstaufrufe
Nach der Anmeldung des Players können Sie jetzt Aufrufe an das PlayFab-Back-End senden. Hier sehen Sie ein Beispiel für einen Aufruf zum Abrufen von Dateien, die in PlayFab für den aktuellen Player gespeichert sind.
Abrufen des EntityKey
Eine Sache, die für einige Aufrufe an PlayFab nützlich sein kann, ist die Kenntnis des PFEntityKey des Spielers. Sobald Sie über ein PFEntityToken verfügen, können Sie einen PFEntityKey mit PFEntityGetEntityKey abrufen.
PFEntityKey const* pEntityKey{};
std::vector<char> entityKeyBuffer;
size_t size{};
HRESULT hr = PFEntityGetEntityKeySize(entityHandle, &size); // Add your own error handling when FAILED(hr) == true
entityKeyBuffer.resize(size);
hr = PFEntityGetEntityKey(entityHandle, entityKeyBuffer.size(), entityKeyBuffer.data(), &pEntityKey, nullptr);
Aufrufen von GetFiles
Alle PlayFab-Aufrufe folgen einem ähnlichen Muster: Vorbereiten des Anforderungsobjekts, Ausführen des Aufrufs (mit PFEntityHandle von login), Erstellen eines Objekts zum Empfangen der Antwort und aufrufen dann eine GetResult-Funktion , um den neu erstellten Container auszufüllen.
XAsyncBlock async{};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = pEntityKey;
HRESULT hr = PFDataGetFilesAsync(entityHandle, &requestFiles, &async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
size_t resultSize;
hr = PFDataGetFilesGetResultSize(&async, &resultSize);
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
hr = PFDataGetFilesGetResult(&async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
Bereinigen
Wenn Ihr Spiel zum Herunterfahren bereit ist oder Sie PlayFab aus einem anderen Grund sauber müssen, stellen Sie sicher, dass Sie alle geöffneten Handles schließen und PFServicesUninitializeAsync aufrufen.
PFEntityCloseHandle(entityHandle);
entityHandle = nullptr;
PFServiceConfigCloseHandle(serviceConfigHandle);
serviceConfigHandle = nullptr;
XAsyncBlock async{};
HRESULT hr = PFServicesUninitializeAsync(&async); // Add your own error handling when FAILED(hr) == true
hr = XAsyncGetStatus(&async, true); // This is doing a blocking wait for completion, but you can use the XAsyncBlock to set a callback instead for async style usage
Asynchrones API-Muster
Das PlayFab Services SDK folgt dem im GDK implementierten asynchronen Programmiermodell . Dieses Programmiermodell umfasst die Verwendung von Aufgaben und Aufgabenwarteschlangen, die von der XAsync-Bibliothek bereitgestellt werden. Dieses Modell ist konsistent mit anderen GDK-Funktionen und -Erweiterungen (z. B. der Xbox Services-API). Dies führt zwar zu einer gewissen Komplexität, bietet aber auch ein hohes Maß an Kontrolle über asynchrone Vorgänge.
In diesem Beispiel wird gezeigt, wie Sie pfDataGetFilesAsync asynchron aufrufen.
auto async = std::make_unique<XAsyncBlock>();
async->callback = [](XAsyncBlock* async)
{
std::unique_ptr<XAsyncBlock> asyncBlockPtr{ async }; // take ownership of XAsyncBlock
size_t resultSize;
HRESULT hr = PFDataGetFilesGetResultSize(async, &resultSize);
if (SUCCEEDED(hr))
{
std::vector<char> getFilesResultBuffer(resultSize);
PFDataGetFilesResponse* getFilesResponseResult{ nullptr };
PFDataGetFilesGetResult(async, getFilesResultBuffer.size(), getFilesResultBuffer.data(), &getFilesResponseResult, nullptr);
}
};
PFDataGetFilesRequest requestFiles{};
requestFiles.entity = m_pEntityKey;
HRESULT hr = PFDataGetFilesAsync(m_entityHandle, &requestFiles, async.get());
if (SUCCEEDED(hr))
{
async.release(); // at this point, the callback will be called so release the unique ptr
}
Fehlerbehandlung
Abgeschlossene XAsync-Vorgänge geben HTTP-status-Codes zurück. Ein Fehler status Code manifestiert sich als Fehler-HRESULT, z. B. HTTP_E_STATUS_NOT_FOUND beim Aufrufen von XAsyncGetStatus() oder einer der PF*Get()-APIs.
Ausführliche Fehlermeldungen, die vom Dienst zurückgegeben werden, finden Sie im nächsten Abschnitt zum Debuggen. Diese detaillierten Fehlermeldungen können während der Entwicklung nützlich sein, um besser zu verstehen, wie der PlayFab-Dienst auf Anforderungen vom Client reagiert.
Debuggen
Die einfachste Möglichkeit, die Ergebnisse anzuzeigen und Aufrufe im PlayFab Services SDK zu debuggen, besteht darin, die Debugablaufverfolgung zu aktivieren. Wenn Sie die Debugablaufverfolgung aktivieren, können Sie sowohl die Ergebnisse im Ausgabefenster des Debuggers anzeigen als auch die Ergebnisse in die eigenen Protokolle Ihres Spiels einbinden.