開始使用 C++ 適用的 Play 遊戲服務

Google Play 遊戲服務 C++ SDK 提供的 C++ API 可與 Google Play 遊戲服務搭配使用,專供已採用遊戲 C++ 實作的開發人員使用。

目前,SDK 會實作下列服務:

  • 授權
  • 成就
  • 排行榜
  • 活動
  • 遊戲進度存檔
  • 鄰近連線 (僅限 Android)
  • 玩家統計數據

概念

一般來說,使用 SDK 的步驟如下:

  1. 設定 Android 平台。
  2. 使用 GameServices::Builder 設定並建構 GameServices 物件。GameServices 物件會自動嘗試登入,並透過 OnAuthActionFinished() 回呼傳回結果。記下回呼傳回的結果。如果自動登入嘗試失敗,您可以顯示相關按鈕,讓使用者登入。
  3. 收到 OnAuthActionFinished() 結果後,您可以使用 GameServices 物件及其子項管理員發出 Play 遊戲服務呼叫,包括:

    • 登入 (授權失敗後):StartAuthorizationUI()
    • 解鎖成就:Achievements().Unlock()
    • 使用內建 UI 顯示成就:Achievements().ShowAllUI()
    • 提交最高分:Leaderboards().SubmitScore()
    • 登出:SignOut()
  4. 使用 GameServices 物件後,請重設或刪除該物件。

更詳細說明:

  1. 初始化平台設定:這個物件包含平台專屬的初始化資訊。在 Android 平台上,平台設定包含 Java VM 和目前 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 執行個體是使用 GameServices::Builder 建立的。

    在大多數實作項目中,只要 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. 使用 Manager 類別來管理 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 和 Manager 方法都具有執行緒安全的非同步實作。可在沒有外部鎖定的情況下的任何執行緒上呼叫,且會按照與叫用順序相同的順序執行。

存取子方法 (讀取狀態) 有兩種主要變體。第一種方法 (名稱如 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);});

所有使用者回呼都會在專用的回呼執行緒上叫用。這個執行緒可能與「主執行緒」或「UI 執行緒」的任何平台概念都不同。此外,您也應該確保使用者回呼能夠快速執行;卡住的回呼執行緒可能會導致使用者出現問題 (例如延遲完成登出要求)。

平台相關資訊

如要開始在 Android 上使用 Play 遊戲 C++ SDK,請繼續參閱快速入門指南

延伸閱讀

請務必詳閱 Google Play 遊戲服務 C++ SDK 中的類別說明文件,並查看如何使用相關 SDK 的範例。

如果您的遊戲使用後端伺服器,請參閱啟用 Google Play 遊戲服務的伺服器端存取權一文。