面向 C++ 的 Play 游戏服务使用入门

Google Play 游戏服务 C++ SDK 提供了可与 Google Play 游戏服务配合使用的 C++ API,专为已有 C++ 游戏实现的开发者而设计。

该 SDK 目前实现了以下服务:

  • 授权
  • 成就
  • 排行榜
  • 回合制多人游戏
  • 实时多人游戏
  • 活动和任务
  • 游戏存档
  • 附近连接(仅限 Android)
  • 玩家统计信息

概念

大体上讲,您需要执行以下步骤来使用 SDK:

  1. 为 Android 设置平台配置。
  2. 使用 GameServices::Builder 配置和构建一个 GameServices 对象。GameServices 对象会自动尝试登录,并通过 OnAuthActionFinished() 回调返回结果。记下回调所返回的结果。如果自动登录尝试失败,您可以显示一个按钮供用户手动登录。
  3. 收到 OnAuthActionFinished() 结果后,您可以使用 GameServices 对象及其子对象管理器来进行 Play 游戏服务调用,包括:

    • 登录(授权失败后):StartAuthorizationUI()
    • 解锁成就:Achievements().Unlock()
    • 使用内置界面显示成就:Achievements().ShowAllUI()
    • 提交最高得分:Leaderboards().SubmitScore()
    • 退出:SignOut()
  4. 当您使用完 GameServices 对象时,请将其重置或销毁。

详细来说,您需要执行以下步骤:

  1. 初始化平台配置:这是一个包含平台特定初始化信息的对象。在 Android 上,平台配置包含 Java 虚拟机和指向当前 Activity 的指针:

    // 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. 构建一个 GameServices 对象:该对象是 Google Play 游戏服务功能的主要入口点。使用 GameServices::Builder 创建 GameServices 实例。

    在大多数实现中,只要您的 C 环境持续存在,给定 GameServices 对象就会持续存在;在 Android Activity 暂停和恢复时,您无需重新初始化该对象。

    // 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. 使用管理器类来管理 GameServices 对象。管理器可通过 GameServices 实例访问,用于将相关功能集合在一起,例如成就管理器和排行榜管理器。它们本身不含用户可见状态。管理器由引用返回,所含的 GameServices 实例可控制其生命周期。您的客户端绝不应保留管理器引用,而应保留 GameServices 实例。

    管理器通过常量值类型的对象返回数据。这些值可一致地反映执行查询所对应时刻的基础数据情况。

    // Submit a high score
    game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
    
    // Show the default Achievements UI
    game_services_->Achievements().ShowAllUI();
    
  4. 当您使用完 GameServices 对象后,通过以下方式进行清理:在拥有该对象的 unique_ptr 上调用 reset(),或者在超出使用期限后让 unique_ptr 自动销毁它。

线程模型

除非另有说明,否则所有 GameServices 和管理器方法都拥有线程安全异步实现。它们可在任何线程上调用,无需外部锁定,并且执行顺序与其调用顺序一致。

访问器方法(读取状态的方法)具有两种主要变体。第一种方法(名称类似 FetchProperty())以异步方式将其结果提供给所提供的回调;第二种方法(名称类似 FetchPropertyBlocking())以同步方式将其结果返回给调用线程。

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

所有用户回调均在一个专用回调线程上调用。该线程可能不同于“主线程”或“界面线程”的任何平台概念。您还应尽力确保用户回调能快速执行;回调线程停止可能会引起用户可见问题(例如,注销请求延迟完成)。

平台特定信息

要开始在 Android 上使用 Play 游戏 C++ SDK,请继续阅读快速入门指南

深入阅读

务必阅读 Google Play 游戏服务 C++ SDK 自带的类文档以了解更多详情,并查看演示 SDK 使用方法的示例