Schnellstart: Linux
Erste Schritte mit dem PlayFab Services SDK für Linux. 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 von Linux durchfü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.
- Ubuntu 22.04 oder höher oder Windows-Subsystem für Linux mit Ubuntu 22.04-Distribution oder höher. Weitere Informationen finden Sie unter Installieren von Linux unter Windows mit WSL. Andere Linux-Distributionen sollten funktionieren, wurden aber nicht überprüft.
Projekteinrichtung
Laden Sie das PlayFab Linux SDK von der Releaseseite des PlayFab SDK in Ihr Projekt herunter.
Integrieren des PlayFab C SDK in Ihr eigenes Projekt
Hinzufügen von Binärdateien zu Ihrem Spiel
Sie müssen die freigegebenen Objektdateien (.so) in Ihr Projekt integrieren. Sie können die Binärdateien selbst erstellen oder von der Releaseseite herunterladen.
Diese nächsten Schritte werden unter der Annahme geschrieben, dass Sie ein neues Projekt erstellt haben.
Hinzufügen der SO-Dateien
Diese Dateien werden mithilfe von CMake in Ihr Projekt integriert.
Entzippen Sie das PlayFab SDK für Linux-Release, und platzieren Sie den Inhalt im gewünschten Verzeichnis.
Fügen Sie target_include_directories oder einer anderen entsprechenden Funktion diese Liste der Header aus der PlayFab SDK-Version hinzu:
Beispiel:
target_include_directories(
[YOUR PROJECT NAME]
"[LOCATION OF PLAYFAB LINUX SDK]/include"
)
- Verknüpfen Sie mit target_link_libraries oder einer anderen entsprechenden Funktion die Speicherorte der SO-Dateien mit Ihrem Projekt.
Beispiel:
set(PLAYFAB_SERVICES_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabServices.Linux.so")
set(PLAYFAB_CORE_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/PlayFabCore.Linux.so")
set(LIBHTTPCLIENT_PATH "[LOCATION OF PLAYFAB LINUX SDK]/bin/libHttpClient.Linux.so")
target_link_librariesc(
[YOUR PROJECT NAME]
${PLAYFAB_SERVICES_PATH}
${PLAYFAB_CORE_PATH}
${LIBHTTPCLIENT_PATH}
)
Ihr Projekt ist jetzt vollständig für die Verwendung des PlayFab Services SDK für Linux eingerichtet. Führen Sie die nächsten Schritte aus, damit einige Beispielaufrufe funktionieren.
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
TBD
Sobald Sie über eine PFServiceConfigHandle verfügen, können Sie es verwenden, um einen Spieleranmeldeanruf zu tätigen. Verwenden Sie im SDK eine PFAuthenticationLoginWith*Async-Methode wie PFAuthenticationLoginWithCustomIDAsync. Mit dieser Funktion können Sie sich mit einer benutzerdefinierten ID 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.
PFAuthenticationLoginWithCustomIDRequest request{};
request.createAccount = true;
request.customId = "player1";
XAsyncBlock async{};
HRESULT hr = PFAuthenticationLoginWithCustomIDAsync(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 = PFAuthenticationLoginWithCustomIDGetResultSize(&async, &bufferSize);
loginResultBuffer.resize(bufferSize);
PFEntityHandle entityHandle{ nullptr };
hr = PFAuthenticationLoginWithCustomIDGetResult(&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.