Início rápido: Win32

Comece a usar o SDK do PlayFab Services para Win32. 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 SDK para Win32. 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 2022 instalado.

Configuração do projeto

Baixe o SDK do PlayFab para o seu projeto na página de releases do SDK do PlayFab. Importe PlayFabServicesSDK.Win32.props para o seu projeto. Você pode fazer isso manualmente no arquivo de projeto ou abrindo a janela Property Manager no Visual Studio, clicando com o botão direito do mouse no projeto e escolhendo Add Existing Property Sheet.

Solução de problemas

Se você tiver problemas para vincular o SDK ao seu projeto, talvez seja necessário instalar as ferramentas de build e as libs 17.5 pelo Visual Studio Installer. Clique em Modify no VS2022 e instale estes dois componentes.

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 SDK, use um método PFAuthenticationReLoginWith*Async, como PFAuthenticationLoginWithSteamAsync. Essa função permite fazer login de um jogador no PlayFab usando um SteamTicket. 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.

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

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 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: Win32

​Requisitos

​Configuração do projeto

​Solução de problemas

​Inicialização e login

​Cabeçalhos

​Inicialização

​Fazendo login

​Chamadas de serviço

​Obtendo a EntityKey

​Chamando GetFiles

​Limpeza

​Padrão de API assíncrona

​Tratamento de erros

​Depuração

​Referência