実績

このドキュメントでは、C++ ゲームで Google Play Games サービスの実績を使用する方法について説明します。このドキュメントは、Google Play ゲームサービスをセットアップするで説明されているとおりにプロジェクトをセットアップしていることを前提としています。アチーブメント API は PgsAchievementsClient にあります。

始める前に

ゲームの実績に関するコンセプトをまだ確認されていない場合は、確認することをおすすめします。

実績 API を使用してコーディングを開始する前に:

実績クライアントを取得する

実績 API の使用を開始するには、まず PgsAchievementsClient オブジェクトを取得する必要があります。そのためには、PgsAchievementsClient_create メソッドを呼び出してアクティビティを渡します。

実績のロックを解除する

実績のロックを解除するには、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 Games サービスでは、必要なステップ数に達すると、実績が自動的にロック解除されます。

実績 ID を strings.xml ファイルで定義して、リソース 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
    );
}

次の画像は、デフォルトの実績 UI の例を示しています。

デフォルトの実績 UI の例
デフォルトの実績 UI の例。