Başarılar

Bu belgede, C++ oyunlarında Google Play Games Hizmetleri başarılarının nasıl kullanılacağı açıklanmaktadır. Bu belgede, projenizi Google Play Games Hizmetleri'ni ayarlama bölümünde açıklandığı şekilde ayarladığınız varsayılır. Başarılar API'sini PgsAchievementsClient içinde bulabilirsiniz.

Başlamadan önce

Henüz yapmadıysanız başarılarla ilgili oyun kavramlarını incelemeniz faydalı olabilir.

Başarılar API'sini kullanarak kod yazmaya başlamadan önce:

Başarılar istemcisi edinme

Başarılar API'sini kullanmaya başlamak için oyununuzun önce bir PgsAchievementsClient nesnesi alması gerekir. Bunu, PgsAchievementsClient_create yöntemini çağırıp etkinliği ileterek yapabilirsiniz.

Başarıların kilidini açma

Bir başarının kilidini açmak için PgsAchievementsClient_unlock yöntemini çağırın ve PgsAchievementsClient ile başarı kimliğini iletin.

Aşağıdaki kod snippet'i, uygulamanızın başarıların kilidini nasıl açabileceğini gösterir:

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

Başarı artımlı türdeyse (yani kilidini açmak için birkaç adım gerekiyorsa) bunun yerine PgsAchievementsClient_increment işlevini çağırın.

Aşağıdaki kod snippet'i, uygulamanızın oyuncunun başarısını nasıl artırabileceğini gösterir:

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

Başarının kilidini açmak için ek kod yazmanız gerekmez. Google Play Games Hizmetleri, gerekli adım sayısına ulaşıldığında başarıyı otomatik olarak açar.

Başarı kimliklerini strings.xml dosyasında tanımlamak iyi bir uygulamadır. Böylece oyununuz, kaynak kimliğine göre başarılara başvurabilir. Başarıları güncellemek ve yüklemek için çağrı yaparken API kotanızı aşmamak için aşağıdaki en iyi uygulamaları da uyguladığınızdan emin olun.

Görüntülü Reklam Ağı sertifikaları

Bir oyuncunun başarılarını göstermek için PgsAchievementsClient_showAchievementsUI işlevini çağırın.

Aşağıdaki kod snippet'i, uygulamanızın varsayılan başarı kullanıcı arayüzünü nasıl gösterebileceğini gösterir.

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

Aşağıdaki resimde, varsayılan başarılar kullanıcı arayüzünün bir örneği gösterilmektedir:

Varsayılan başarılar kullanıcı arayüzü örneği
Varsayılan başarılar kullanıcı arayüzü örneği.