Início rápido: GDK

Comece a usar o SDK do PlayFab Services para o Microsoft Game Development Kit (GDK). Siga estas etapas para incluir as bibliotecas no seu projeto e experimentar o código de exemplo da funcionalidade básica do PlayFab. Este início rápido ajuda você a fazer sua primeira chamada à API do PlayFab usando o GDK. Antes de continuar, verifique se você concluiu as etapas de Início rápido: Game Manager, que garantem que você tenha uma conta do PlayFab e esteja familiarizado com o PlayFab Game Manager.

Requisitos

Uma conta de desenvolvedor do PlayFab.
Visual Studio 2019 ou 2022 instalado.
- Para obter mais informações sobre os requisitos do Visual Studio para o desenvolvimento com o GDK, consulte Requisitos do SDK e das ferramentas.

Configuração do projeto

Assim como outras bibliotecas de extensão do GDK, adicione o SDK do PlayFab Services pelas propriedades do projeto. Nas Configuration Properties do projeto, em Gaming Desktop > General, selecione Gaming Extension Libraries. No prompt, marque PlayFab.Services.C.

Selecionar a biblioteca de extensão PlayFab.Services.C

Cabeçalhos

Inclua PFServices.h para ter acesso a toda a funcionalidade do PlayFab incluída:

#include <playfab/services/PFServices.h>

Inicialização

A inicialização do PlayFab requer duas chamadas de função: PFServicesInitialize e PFServiceConfigCreateHandle. O resultado dessa inicialização é um PFServiceConfigHandle. Você fornece esse identificador a uma chamada de login subsequente, direcionando a chamada para o título correto no back-end do 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);

Depois de ter um PFServiceConfigHandle, você pode usá-lo para fazer uma chamada de login de jogador. No GDK, use PFAuthenticationLoginWithXUserAsync. Essa função permite fazer login de um jogador no PlayFab usando um XUserHandle. Para saber mais sobre como obter e gerenciar um XUserHandle, consulte Identidade do usuário e XUser. Depois de fazer uma chamada de login, você pode verificar o status da chamada com XAsyncGetStatus. O status começa como E_PENDING e muda para S_OK depois que a chamada é concluída com êxito. Se a chamada falhar por algum motivo, o status refletirá essa falha. O tratamento de erros em todas as chamadas do PlayFab Services funciona dessa forma. Junto com um resultado S_OK, você recebe um PFEntityHandle. Use esse identificador para fazer as chamadas subsequentes do PlayFab como o jogador conectado. Ele inclui todo o material necessário para se autenticar no serviço PlayFab como esse jogador.

    PFAuthenticationLoginWithXUserRequest request{};
    request.createAccount = true;
    request.user = userHandle; // An XUserHandle obtained from XUserAddAsync

    XAsyncBlock async{};
    HRESULT hr = PFAuthenticationLoginWithXUserAsync(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 = PFAuthenticationLoginWithXUserGetResultSize(&async, &bufferSize);
    loginResultBuffer.resize(bufferSize);

    PFEntityHandle entityHandle{ nullptr };
    hr = PFAuthenticationLoginWithXUserGetResult(&async, &entityHandle, loginResultBuffer.size(), loginResultBuffer.data(), &loginResult, nullptr);

Tratando a suspensão e a retomada

Os jogos do GDK podem ficar suspensos por longos períodos (por exemplo, por meio do Quick Resume). Se o token de entidade expirar durante a suspensão, o SDK detectará isso na retomada e notificará seu jogo. Você deve se registrar no TokenExpiredHandler no início do ciclo de vida do jogo para poder se autenticar novamente e reconectar os serviços quando necessário. Para obter todos os detalhes, consulte Tratando a expiração de tokens.

Chamadas de serviço

Depois de fazer login do jogador, você pode fazer chamadas ao back-end do PlayFab. Veja um exemplo de chamada para obter os arquivos armazenados no PlayFab para o jogador atual.

Obtendo a EntityKey

Algo que pode ser útil em algumas chamadas ao PlayFab é conhecer a PFEntityKey do jogador. Depois de ter um PFEntityToken, você pode recuperar uma PFEntityKey com 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);

Chamando GetFiles

Todas as chamadas do PlayFab seguem um padrão semelhante: preparar o objeto de solicitação, fazer a chamada (usando o PFEntityHandle do login), criar um objeto para receber a resposta e, em seguida, chamar uma função GetResult para preencher o contêiner recém-criado.

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

Limpeza

Quando seu jogo estiver pronto para ser desligado ou você precisar limpar o PlayFab por algum outro motivo, feche todos os identificadores abertos e chame 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

Padrão de API assíncrona

O SDK do PlayFab Services para o GDK segue o modelo de programação assíncrona implementado no GDK. Esse modelo de programação envolve o uso de tarefas e filas de tarefas fornecidas pela biblioteca XAsync. Esse modelo é consistente com outras funções e extensões do GDK (como a API do XBOX Services). Embora introduza alguma complexidade, ele também oferece um alto grau de controle sobre as operações assíncronas. Este exemplo mostra como fazer uma chamada assíncrona a 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
    }

Tratamento de erros

As operações XAsync concluídas retornam códigos de status HTTP. Um código de status de erro se manifesta como um HRESULT de falha, como HTTP_E_STATUS_NOT_FOUND, ao chamar XAsyncGetStatus() ou uma das APIs PF*Get(). Para ver as mensagens de erro detalhadas retornadas pelo serviço, consulte a próxima seção sobre depuração. Essas mensagens de erro detalhadas podem ser úteis durante o desenvolvimento para entender melhor como o serviço PlayFab reage às solicitações do cliente.

Depuração

A maneira mais fácil de ver os resultados e depurar qualquer chamada no SDK do PlayFab Services é habilitar o rastreamento de depuração. Habilitar o rastreamento de depuração permite tanto ver os resultados na janela de saída do depurador quanto conectar os resultados aos logs do próprio jogo.

Referência

Documentação de referência da API

​Início rápido: GDK

​Requisitos

​Configuração do projeto

​Inicialização e login

​Cabeçalhos

​Inicialização

​Fazendo login

​Tratando a suspensão e a retomada

​Chamadas de serviço

​Obtendo a EntityKey

​Chamando GetFiles

​Limpeza

​Padrão de API assíncrona

​Tratamento de erros

​Depuração

​Referência