Início rápido: Linux

Comece a usar o SDK do PlayFab Services para Linux. 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 Linux. 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.
Ubuntu 22.04 ou superior, ou o Subsistema do Windows para Linux com a distribuição Ubuntu 22.04 ou superior. Consulte Como instalar o Linux no Windows com o WSL. Outras distribuições Linux devem funcionar, mas não foram verificadas.

Configuração do projeto

Baixe o SDK do PlayFab para Linux para o seu projeto na página de releases do SDK do PlayFab.

Integrar o SDK do PlayFab para C ao seu projeto

Adicionar os binários ao seu jogo

Você precisará integrar ao seu projeto os arquivos de objeto compartilhado (.so). Você pode compilar os binários por conta própria ou baixá-los da página de releases. As próximas etapas foram escritas considerando que você criou um novo projeto.

Adicionando os arquivos .so

Esses arquivos são integrados ao seu projeto usando o CMake.

Descompacte o release do SDK do PlayFab para Linux e coloque o conteúdo no diretório desejado.
Usando target_include_directories ou outra função equivalente, adicione esta lista de cabeçalhos do release do SDK do PlayFab:

Por exemplo:

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

Usando target_link_libraries ou outra função equivalente, vincule os locais dos arquivos .so ao seu projeto.

Por exemplo:

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

Agora seu projeto está totalmente configurado para usar o SDK do PlayFab Services para Linux. Siga as próximas etapas para fazer algumas chamadas de exemplo funcionarem.

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

A definir Depois de ter um PFServiceConfigHandle, você pode usá-lo para fazer uma chamada de login de jogador. No SDK, use um método PFAuthenticationLoginWith*Async, como PFAuthenticationLoginWithCustomIDAsync. Essa função permite fazer login de um jogador no PlayFab usando uma ID personalizada. 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.

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

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

​Requisitos

​Configuração do projeto

​Integrar o SDK do PlayFab para C ao seu projeto

​Adicionar os binários ao seu jogo

​Adicionando os arquivos .so

​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