В этом документе описывается, как использовать достижения Google Play Games Services в играх на C++. Предполагается, что ваш проект настроен, как описано в разделе «Настройка Google Play Games Services» . API достижений можно найти в PgsAchievementsClient .
Прежде чем начать
Если вы еще этого не сделали, вам может быть полезно ознакомиться с основными принципами игры, связанными с достижениями .
Прежде чем начать писать код, используя API достижений:
Следуйте инструкциям по установке и настройке вашего приложения для использования сервисов Play Games, приведенным в руководстве «Настройка сервисов Google Play Games» .
Определите, какие достижения вы хотите разблокировать или отображать в своей игре, следуя инструкциям в руководстве Google Play Console .
Ознакомьтесь с рекомендациями, описанными в Контрольном списке качества .
Get an achievements client
Для начала использования API достижений ваша игра должна сначала получить объект PgsAchievementsClient . Это можно сделать, вызвав метод PgsAchievementsClient_create и передав в него объект Activity.
Разблокировать достижения
Чтобы разблокировать достижение, вызовите метод PgsAchievementsClient_unlock и передайте в него объект PgsAchievementsClient и идентификатор достижения.
Следующий фрагмент кода показывает, как ваше приложение может разблокировать достижения:
// Example Usage void TriggerUnlock(PgsGamesClient* gamesClient) { // You must obtain the achievements client from the main games client PgsAchievementsClient* achievementsClient = PgsGamesClient_getAchievementsClient(gamesClient); // Replace with your actual Achievement ID from the Play Console const char* MY_ACHIEVEMENT_ID = "CgkI...sQw"; UnlockAchievement(achievementsClient, MY_ACHIEVEMENT_ID); }
Если достижение относится к типу "инкрементальное " (то есть для его разблокировки требуется несколько шагов), вызовите вместо этого PgsAchievementsClient_increment .
Следующий фрагмент кода показывает, как ваше приложение может увеличить достижение игрока:
void IncrementMyAchievement(PgsAchievementsClient* client, const char* achievementId, uint32_t steps) { if (client == nullptr) { return; } // Call the API // Parameters typically include: // 1. Client handle // 2. Achievement ID (string) // 3. Number of steps to increment by (For example, 1) // 4. Callback function // 5. User context (passed to callback) PgsAchievementsClient_increment( client, achievementId, steps, OnIncrementCallback, (void*)achievementId // Pass ID as context so the callback knows which one finished ); } // Example Usage in Game Loop void OnEnemyDefeated(PgsGamesClient* gamesClient) { // Get the achievements client handle PgsAchievementsClient* achievementsClient = PgsGamesClient_getAchievementsClient(gamesClient); // ID from Google Play Console const char* ACH_ENEMY_KILLER = "CgkI...xyz"; // Increment by 1 step IncrementMyAchievement(achievementsClient, ACH_ENEMY_KILLER, 1); }
Для разблокировки достижения не требуется писать дополнительный код; Google Play Games Services автоматически разблокирует достижение после выполнения необходимого количества шагов.
Рекомендуется определять идентификаторы достижений в файле strings.xml , чтобы ваша игра могла ссылаться на достижения по идентификатору ресурса. При выполнении запросов на обновление и загрузку достижений также обязательно следуйте этим рекомендациям , чтобы избежать превышения квоты API.
Display achievements
Чтобы отобразить достижения игрока, вызовите функцию PgsAchievementsClient_showAchievementsUI .
Приведённый ниже фрагмент кода показывает, как ваше приложение может отображать стандартный пользовательский интерфейс достижений.
void OnShowAchievementsUICallback(void* context, PgsError error) { if (error == PgsError_Success) { // The UI was displayed and closed successfully by the user. // You might resume your game loop here if it was paused. } else { // Handle error (For example,, user not signed in, UI failed to load). } } // Function to trigger the Achievements UI void ShowMyAchievements(PgsAchievementsClient* achievementsClient) { if (achievementsClient == nullptr) { // Log error: Client not initialized return; } // Call the API // Note: The specific arguments often include the client, a callback, and user_data. // Some versions might require the Android Activity or a Request Code as well. PgsAchievementsClient_showAchievementsUI( achievementsClient, OnShowAchievementsUICallback, // Callback function nullptr // Optional user data (context) passed to callback ); }
На следующем изображении показан пример стандартного пользовательского интерфейса достижений:
