Достижения

В этом документе описывается, как использовать достижения 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
    );
}

На следующем изображении показан пример стандартного пользовательского интерфейса достижений:

Example of the default achievements UI.