Pencapaian

Dokumen ini menjelaskan cara menggunakan pencapaian Layanan game Google Play dalam game C++. Dokumen ini mengasumsikan bahwa Anda telah menyiapkan project seperti yang dijelaskan dalam Menyiapkan Layanan game Play. Anda dapat menemukan API pencapaian di PgsAchievementsClient.

Sebelum memulai

Jika Anda belum melakukannya, sebaiknya tinjau konsep game pencapaian.

Sebelum Anda mulai membuat kode menggunakan API pencapaian:

• Ikuti petunjuk penginstalan dan penyiapan aplikasi untuk menggunakan Layanan game Play di panduan Menyiapkan Layanan game Google Play.

• Tentukan pencapaian yang ingin Anda buka atau tampilkan pada game dengan mengikuti petunjuk di Panduan Konsol Google Play.

• Pahami rekomendasi yang dijelaskan dalam Checklist Kualitas.

Mendapatkan klien pencapaian

Untuk mulai menggunakan API pencapaian, game Anda harus mendapatkan objek PgsAchievementsClient terlebih dahulu. Anda dapat melakukannya dengan memanggil metode PgsAchievementsClient_create dan meneruskan aktivitas.

Membuka pencapaian

Untuk membuka pencapaian, panggil metode PgsAchievementsClient_unlock dan teruskan PgsAchievementsClient dan ID pencapaian.

Cuplikan kode berikut menunjukkan cara aplikasi Anda membuka pencapaian:

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

Jika pencapaian adalah jenis inkremental (yaitu, beberapa langkah diperlukan untuk membuka kuncinya), panggil PgsAchievementsClient_increment sebagai gantinya.

Cuplikan kode berikut menunjukkan cara aplikasi Anda meningkatkan pencapaian pemain:

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

Anda tidak perlu menulis kode tambahan untuk membuka pencapaian; Layanan game Google Play akan otomatis membuka pencapaian setelah mencapai jumlah langkah yang diperlukan.

Praktik yang baik adalah menentukan ID pencapaian dalam file strings.xml, sehingga game Anda dapat mereferensikan pencapaian berdasarkan ID resource. Saat melakukan panggilan untuk memperbarui dan memuat pencapaian, pastikan Anda juga mengikuti praktik terbaik ini agar tidak melebihi kuota API.

Menampilkan pencapaian

Untuk menampilkan pencapaian pemain, panggil PgsAchievementsClient_showAchievementsUI.

Cuplikan kode berikut menunjukkan cara aplikasi Anda menampilkan antarmuka pengguna pencapaian default.

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

Gambar berikut menunjukkan contoh UI pencapaian default:

Contoh UI pencapaian default.