Google Play 遊戲服務 C++ SDK 提供的 C++ API 可與 Google Play 遊戲服務搭配使用,專供已採用遊戲 C++ 實作的開發人員使用。
目前,SDK 會實作下列服務:
- 授權
- 成就
- 排行榜
- 活動
- 遊戲進度存檔
- 鄰近連線 (僅限 Android)
- 玩家統計數據
概念
一般來說,使用 SDK 的步驟如下:
- 設定 Android 平台。
- 使用
GameServices::Builder
設定並建構GameServices
物件。GameServices
物件會自動嘗試登入,並透過OnAuthActionFinished()
回呼傳回結果。記下回呼傳回的結果。如果自動登入嘗試失敗,您可以顯示相關按鈕,讓使用者登入。 收到
OnAuthActionFinished()
結果後,您可以使用GameServices
物件及其子項管理員發出 Play 遊戲服務呼叫,包括:- 登入 (授權失敗後):
StartAuthorizationUI()
- 解鎖成就:
Achievements().Unlock()
- 使用內建 UI 顯示成就:
Achievements().ShowAllUI()
- 提交最高分:
Leaderboards().SubmitScore()
- 登出:
SignOut()
- 登入 (授權失敗後):
使用
GameServices
物件後,請重設或刪除該物件。
更詳細說明:
初始化平台設定:這個物件包含平台專屬的初始化資訊。在 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);
建構
GameServices
物件:這個物件是 Google Play 遊戲服務功能的主要進入點。GameServices
執行個體是使用GameServices::Builder
建立的。在大多數實作項目中,只要 C 環境持續存在,指定
GameServices
物件就會持續存在;當 AndroidActivity
暫停和繼續時,您不需要重新初始化該物件。// 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);
使用 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();
使用
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 遊戲服務的伺服器端存取權一文。