업적

이 문서에서는 C++ 게임에서 Google Play 게임즈 서비스 업적을 사용하는 방법을 설명합니다. 이 문서에서는 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 게임즈 서비스에서는 필요한 단계 수에 도달하면 자동으로 업적이 달성됩니다.

게임에 리소스 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의 예.