Primeiros passos com os serviços relacionados a jogos do Google Play para C++

O SDK C++ dos serviços relacionados a jogos do Google Play fornece uma API C++ para uso com esses serviços. Ele destina-se a desenvolvedores que têm uma implementação C++ do jogo.

Atualmente, o SDK implementa os seguintes serviços:

  • Autorização
  • Conquista
  • Placares
  • Multijogador com base em turnos
  • Multijogador em tempo real
  • Eventos e missões
  • Jogos salvos
  • Nearby Connections (somente Android)
  • Estatísticas do jogador

Conceitos

Em um alto nível, use o SDK seguindo estes passos:

  1. Defina a configuração de plataforma para Android.
  2. Use um GameServices::Builder para configurar e construir um objeto GameServices. O objeto GameServices tenta fazer login automaticamente e retorna o resultado usando um callback OnAuthActionFinished(). Anote o resultado retornado pelo callback. Se a tentativa de login automático falhar, você poderá exibir um botão para permitir que os usuários façam login.
  3. Depois de receber o resultado de OnAuthActionFinished(), você pode usar o objeto GameServices e os Managers filhos dele para fazer chamadas de serviço do Play Games, incluindo o seguinte:

    • Login depois que a autorização falhar: StartAuthorizationUI()
    • Desbloquear conquistas: Achievements().Unlock()
    • Exibir conquistas usando a IU integrada: Achievements().ShowAllUI()
    • Enviar a maior pontuação: Leaderboards().SubmitScore()
    • Logout: SignOut()
  4. Ao terminar de usar o objeto GameServices, redefina-o ou destrua-o.

Em um nível mais detalhado:

  1. Inicialize uma configuração de plataforma: esse objeto contém informações de inicialização específicas da plataforma. No Android, a configuração da plataforma contém a Java VM e um ponteiro para a Activity atual:

    // In android_main(), create a platform configuration
    // and bind the object activity.
    // Alternately, attach the activity in JNI_Onload().
    gpg::AndroidPlatformConfiguration platform_configuration;
    platform_configuration.SetActivity(state->activity->clazz);
    
  2. Construa um objeto GameServices: esse objeto é o ponto de entrada principal da funcionalidade dos serviços relacionados a jogos do Google Play. Instâncias de GameServices são criadas com o GameServices::Builder.

    Na maioria das implementações, um objeto GameServices persistirá pelo mesmo tempo que o ambiente C. Não é preciso reinicializá-lo quando a Activity do Android é pausada ou retomada.

    // Creates a GameServices object that has lambda callbacks.
    game_services_ = gpg::GameServices::Builder()
            .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
            .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
                is_auth_in_progress_ = true;
                started_callback(op);
            })
            .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                         gpg::AuthStatus status) {
                LOGI("Sign in finished with a result of %d", status);
                is_auth_in_progress_ = false;
                finished_callback(op, status);
            })
            .Create(pc);
    
  3. Use as classes Manager para gerenciar seu objeto GameServices. Os Managers são acessados de uma instância de GameServices e agrupam as funcionalidades relacionadas. Exemplos deles incluem os Managers Achievement e Leaderboard. Eles não contêm estado visível para o usuário por si só. Os Managers são retornados por referência, e a instância de GameServices que os contém controla o ciclo de vida deles. Seu cliente nunca deve manter uma referência ao Manager. Em vez disso, ele precisa manter a instância de GameServices.

    Os Managers retornam dados via objetos do tipo valor imutáveis. Esses valores refletem uma visualização consistente dos dados subjacentes no momento em que a consulta foi feita.

    // Submit a high score
    game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
    
    // Show the default Achievements UI
    game_services_->Achievements().ShowAllUI();
    
  4. Quando você terminar de usar o objeto GameServices, limpe-o chamando reset() no unique_ptr a que ele pertence ou deixando que o unique_ptr o destrua automaticamente ao sair do escopo.

Modelo de encadeamento

A não ser que informado de outra forma, todos os métodos de GameServices e Manager têm implementação assíncrona e segura para linhas de execução. Eles podem ser chamados em qualquer linha de execução sem bloqueio externo e serão executados em uma ordem consistente com a sequência de invocação.

Métodos de acesso (os que leem estado) possuem duas variações principais. O primeiro tipo de método (com nomes como FetchProperty()) fornece assincronamente os resultados para um callback fornecido. O segundo (com nomes como FetchPropertyBlocking()) retorna de forma síncrona os resultados para a linha de execução que o chamou.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Todos os retornos de chamada de usuário são invocados em um encadeamento de retorno de chamada dedicado. Essa linha de execução é potencialmente distinta de qualquer conceito de plataforma de uma "linha de execução principal" ou "linha de execução de IU". Também é importante garantir que os callbacks de usuário sejam executados rapidamente. Uma linha de execução de callback parada pode causar problemas visíveis ao usuário, como o atraso na conclusão de uma solicitação de logout.

Informações específicas de plataforma

Para começar a usar o SDK C++ do Play Games no Android, consulte o guia de início rápido.

Leia mais

Leia a documentação de classe que acompanha o SDK C++ dos serviços relacionados a jogos do Google Play para ver mais detalhes e conferir os exemplos que demonstram como usar o SDK.