Osiągnięcia

W tym dokumencie opisujemy, jak używać osiągnięć w usługach Gier Google Play w grach w języku C++. W tym dokumencie zakłada się, że projekt został skonfigurowany zgodnie z opisem w artykule Konfigurowanie usług Gier Google Play. Interfejs API osiągnięć znajdziesz w PgsAchievementsClient.

Zanim zaczniesz

Jeśli jeszcze tego nie zrobiono, warto zapoznać się z pojęciami dotyczącymi gier z osiągnięciami.

Zanim zaczniesz pisać kod przy użyciu interfejsu API osiągnięć:

• Postępuj zgodnie z instrukcjami instalowania i konfigurowania aplikacji, aby korzystać z usług gier Play, które znajdziesz w przewodniku Konfigurowanie usług gier Google Play.

• Określ osiągnięcia, które mają być odblokowywane lub wyświetlane w Twojej grze, postępując zgodnie z instrukcjami w przewodniku po Konsoli Google Play.

• Zapoznaj się z rekomendacjami opisanymi w liście kontrolnej jakości.

Pobieranie klienta osiągnięć

Aby zacząć korzystać z interfejsu API osiągnięć, gra musi najpierw uzyskać obiekt PgsAchievementsClient. Możesz to zrobić, wywołując metodę PgsAchievementsClient_create i przekazując aktywność.

Odblokowywanie osiągnięć

Aby odblokować osiągnięcie, wywołaj metodę PgsAchievementsClient_unlock i przekaż do niej PgsAchievementsClient oraz identyfikator osiągnięcia.

Ten fragment kodu pokazuje, jak aplikacja może odblokowywać osiągnięcia:

// 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);
}

Jeśli osiągnięcie jest typu wieloetapowego (czyli do jego odblokowania wymagane jest wykonanie kilku czynności), zamiast tego wywołaj PgsAchievementsClient_increment.

Poniższy fragment kodu pokazuje, jak aplikacja może zwiększyć osiągnięcie gracza:

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);
}

Nie musisz pisać dodatkowego kodu, aby odblokować osiągnięcie. Usługi gier Google Play automatycznie odblokowują osiągnięcie, gdy osiągnie ono wymaganą liczbę kroków.

Dobrym rozwiązaniem jest zdefiniowanie identyfikatorów osiągnięć w pliku strings.xml, aby gra mogła odwoływać się do osiągnięć za pomocą identyfikatora zasobu. Podczas wywoływania funkcji aktualizowania i wczytywania osiągnięć pamiętaj, aby postępować zgodnie z tymi sprawdzonymi metodami, aby nie przekroczyć limitu interfejsu API.

Wyświetlanie osiągnięć

Aby wyświetlić osiągnięcia gracza, wywołaj metodę PgsAchievementsClient_showAchievementsUI.

Ten fragment kodu pokazuje, jak aplikacja może wyświetlać domyślny interfejs osiągnięć.

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
    );
}

Obraz poniżej przedstawia przykładowy domyślny interfejs osiągnięć:

Przykład domyślnego interfejsu osiągnięć.