Démarrage rapide : Linux

Prenez en main le SDK PlayFab Services pour Linux. Suivez ces étapes pour inclure les bibliothèques dans votre projet et essayer l’exemple de code des fonctionnalités PlayFab de base. Ce démarrage rapide vous aide à effectuer votre premier appel d’API PlayFab sous Linux. Avant de continuer, assurez-vous d’avoir suivi les étapes de Démarrage rapide : Game Manager, qui garantissent que vous disposez d’un compte PlayFab et que vous connaissez PlayFab Game Manager.

Configuration requise

Un compte de développeur PlayFab.
Ubuntu 22.04 ou version ultérieure, ou le Sous-système Windows pour Linux avec une distribution Ubuntu 22.04 ou ultérieure. Consultez Comment installer Linux sur Windows avec WSL. Les autres distributions Linux devraient fonctionner, mais n’ont pas été vérifiées.

Configuration du projet

Téléchargez le SDK PlayFab Linux dans votre projet depuis la page des versions du SDK PlayFab.

Intégrer le SDK C PlayFab à votre propre projet

Ajouter les binaires à votre jeu

Vous devez intégrer à votre projet les fichiers d’objets partagés (.so). Vous pouvez générer vous-même les binaires ou les télécharger depuis la page des versions. Les étapes suivantes partent du principe que vous avez créé un nouveau projet.

Ajouter les fichiers .so

Ces fichiers sont intégrés à votre projet à l’aide de CMake.

Décompressez la version du SDK PlayFab pour Linux et placez son contenu dans le répertoire de votre choix.
À l’aide de target_include_directories ou d’une autre fonction équivalente, ajoutez cette liste d’en-têtes issue de la version du SDK PlayFab :

Par exemple :

target_include_directories(
    [YOUR PROJECT NAME]
    "[LOCATION OF PLAYFAB LINUX SDK]/include"
)

À l’aide de target_link_libraries ou d’une autre fonction équivalente, liez les emplacements des fichiers .so à votre projet.

Par exemple :

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}
)

Votre projet est désormais entièrement configuré pour utiliser le SDK PlayFab Services pour Linux. Suivez les étapes suivantes pour faire fonctionner quelques exemples d’appels.

Initialisation et connexion

En-têtes

Incluez PFServices.h pour accéder à toutes les fonctionnalités PlayFab incluses :

#include <playfab/services/PFServices.h>

Initialisation

L’initialisation de PlayFab nécessite deux appels de fonction : PFServicesInitialize et PFServiceConfigCreateHandle. Le résultat de cette initialisation est un PFServiceConfigHandle. Vous fournissez ce handle à un appel de connexion ultérieur, afin de diriger l’appel vers le bon titre dans le back-end PlayFab.

    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);

Connexion

À déterminer Une fois que vous disposez d’un PFServiceConfigHandle, vous pouvez l’utiliser pour effectuer un appel de connexion de joueur. Dans le SDK, utilisez une méthode PFAuthenticationLoginWith*Async telle que PFAuthenticationLoginWithCustomIDAsync. Cette fonction vous permet de connecter un joueur à PlayFab à l’aide d’un ID personnalisé. Après un appel de connexion, vous pouvez vérifier l’état de l’appel avec XAsyncGetStatus. L’état est initialement E_PENDING et passe à S_OK une fois l’appel terminé avec succès. Si l’appel échoue pour une raison quelconque, l’état reflète cet échec. La gestion des erreurs fonctionne de cette façon pour tous les appels PlayFab Services. Avec un résultat S_OK, vous obtenez un PFEntityHandle. Vous utilisez ce handle pour effectuer les appels PlayFab suivants en tant que joueur connecté. Il contient tous les éléments nécessaires pour s’authentifier auprès du service PlayFab en tant que ce joueur.

    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);

Appels de service

Une fois le joueur connecté, vous pouvez effectuer des appels au back-end PlayFab. Voici un exemple d’appel permettant d’obtenir les fichiers stockés dans PlayFab pour le joueur actuel.

Obtenir l’EntityKey

Pour certains appels à PlayFab, il peut être utile de connaître la PFEntityKey du joueur. Une fois que vous disposez d’un PFEntityToken, vous pouvez récupérer une PFEntityKey avec PFEntityGetEntityKey.

    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);

Appeler GetFiles

Tous les appels PlayFab suivent un modèle similaire : préparation de l’objet de requête, appel (à l’aide du PFEntityHandle obtenu lors de la connexion), création d’un objet destiné à recevoir la réponse, puis appel d’une fonction GetResult pour remplir le conteneur nouvellement créé.

    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);

Nettoyage

Lorsque votre jeu est prêt à s’arrêter, ou si vous devez nettoyer PlayFab pour une autre raison, assurez-vous de fermer tous les handles ouverts et à appeler PFServicesUninitializeAsync.

    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

Modèle d’API asynchrone

Le SDK PlayFab Services suit le modèle de programmation asynchrone implémenté dans le GDK. Ce modèle de programmation implique l’utilisation de tâches et de files d’attente de tâches fournies par la bibliothèque XAsync. Ce modèle est cohérent avec les autres fonctions et extensions du GDK (comme l’API XBOX Services). Bien qu’il introduise une certaine complexité, il offre également un haut niveau de contrôle sur les opérations asynchrones. Cet exemple montre comment effectuer un appel asynchrone à PFDataGetFilesAsync.

    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
    }

Gestion des erreurs

Les opérations XAsync terminées retournent des codes d’état HTTP. Un code d’état d’erreur se traduit par un HRESULT d’échec, tel que HTTP_E_STATUS_NOT_FOUND, lors de l’appel de XAsyncGetStatus() ou de l’une des API PF*Get(). Pour afficher les messages d’erreur détaillés retournés par le service, consultez la section suivante sur le débogage. Ces messages d’erreur détaillés peuvent être utiles pendant le développement pour mieux comprendre comment le service PlayFab réagit aux requêtes du client.

Débogage

Le moyen le plus simple d’afficher les résultats et de déboguer les appels du SDK PlayFab Services consiste à activer le traçage de débogage. L’activation du traçage de débogage vous permet à la fois d’afficher les résultats dans la fenêtre de sortie du débogueur et de les intégrer aux journaux de votre jeu.

Référence

Documentation de référence de l’API

​Démarrage rapide : Linux

​Configuration requise

​Configuration du projet

​Intégrer le SDK C PlayFab à votre propre projet

​Ajouter les binaires à votre jeu

​Ajouter les fichiers .so

​Initialisation et connexion

​En-têtes

​Initialisation

​Connexion

​Appels de service

​Obtenir l’EntityKey

​Appeler GetFiles

​Nettoyage

​Modèle d’API asynchrone

​Gestion des erreurs

​Débogage

​Référence