成就

本文档介绍了如何在 C++ 游戏中使用 Google Play 游戏服务成就。本文档假定您已按照设置 Google Play 游戏服务中所述设置项目。您可以在 PgsAchievementsClient 中找到成就 API。

准备工作

请阅读成就游戏概念（如果您尚未阅读）。

开始使用成就 API 进行编码之前，请执行以下操作：

获取成就客户端

如需开始使用成就 API，您的游戏必须先获取一个 PgsAchievementsClient 对象。为此，您可以调用 PgsAchievementsClient_create 方法并传入 activity。

解锁成就

如需解锁成就，请调用 PgsAchievementsClient_unlock 方法并传入 PgsAchievementsClient 和成就 ID。

以下代码段展示了应用如何解锁成就：

// 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 游戏服务便会自动解锁成就。

最好在 strings.xml 文件中定义成就 ID，以便游戏按资源 ID 引用成就。在进行调用以更新和加载成就时，请务必遵循相关最佳实践，以免超出您的 API 配额。

显示成就

如需显示玩家的成就，请调用 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
    );
}

下图显示了默认成就界面的示例：

默认成就界面示例
默认成就界面的示例。