Réussites

Ce document explique comment utiliser les succès des services de jeux Google Play dans les jeux C++. Ce document part du principe que vous avez configuré votre projet comme décrit dans Configurer les services de jeux Google Play. L'API Achievements est disponible dans PgsAchievementsClient.

Avant de commencer

Si ce n'est pas déjà fait, n'hésitez pas à revoir les concepts de succès dans les jeux.

Avant de commencer à coder à l'aide de l'API Achievements :

Obtenir un client de succès

Pour commencer à utiliser l'API Achievements, votre jeu doit d'abord obtenir un objet PgsAchievementsClient. Pour ce faire, appelez la méthode PgsAchievementsClient_create et transmettez l'activité.

Débloquer des succès

Pour débloquer un succès, appelez la méthode PgsAchievementsClient_unlock et transmettez l'PgsAchievementsClient et l'ID du succès.

L'extrait de code suivant montre comment votre application peut débloquer des succès :

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

Si le succès est de type incrémentiel (ce qui signifie que plusieurs étapes sont nécessaires pour le débloquer), appelez plutôt PgsAchievementsClient_increment.

L'extrait de code suivant montre comment votre application peut incrémenter le succès du joueur :

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

Vous n'avez aucun code supplémentaire à ajouter pour débloquer le succès. Les services de jeux Google Play le débloquent automatiquement une fois que le nombre d'étapes requis est atteint.

Une bonne pratique consiste à définir les ID de succès dans le fichier strings.xml pour permettre à votre jeu de référencer les succès par ID de ressource. Lorsque vous passez des appels pour mettre à jour et charger des succès, veillez également à suivre ces bonnes pratiques afin d'éviter de dépasser votre quota d'API.

Afficher les succès

Pour afficher les succès d'un joueur, appelez PgsAchievementsClient_showAchievementsUI.

L'extrait de code suivant montre comment votre application peut afficher l'interface utilisateur des succès par défaut.

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

L'image suivante montre un exemple d'interface utilisateur de succès par défaut :

Exemple d'UI de succès par défaut
Exemple d'interface utilisateur de succès par défaut.