Obiettivi

Questo documento descrive come utilizzare gli obiettivi di Google Play Games Services nei giochi C++. Questo documento presuppone che tu abbia configurato il progetto come descritto in Configurare Google Play Games Services. Puoi trovare l'API Achievements in the PgsAchievementsClient.

Prima di iniziare

Se non l'hai ancora fatto, potrebbe essere utile esaminare i concetti di gioco degli obiettivi.

Prima di iniziare a scrivere codice utilizzando l'API Achievements:

Ottenere un client Achievements

Per iniziare a utilizzare l'API Achievements, il tuo gioco deve prima ottenere un PgsAchievementsClient oggetto. Puoi ottenerlo chiamando il PgsAchievementsClient_create metodo e passando l'attività.

Sbloccare gli obiettivi

Per sbloccare un obiettivo, chiama il PgsAchievementsClient_unlock metodo e passa PgsAchievementsClient e l'ID obiettivo.

Il seguente snippet di codice mostra come la tua app può sbloccare gli obiettivi:

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

Se l'obiettivo è di tipo incrementale (ovvero sono necessari diversi passaggi per sbloccarlo), chiama invece PgsAchievementsClient_increment.

Il seguente snippet di codice mostra come la tua app può aumentare l'obiettivo del giocatore:

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

Non devi scrivere codice aggiuntivo per sbloccare l'obiettivo. Google Play Games Services sblocca automaticamente l'obiettivo una volta raggiunto il numero di passaggi richiesto.

Una buona pratica è definire gli ID obiettivo nel file strings.xml, in modo che il gioco possa fare riferimento agli obiettivi in base all'ID risorsa. Quando effettui chiamate per aggiornare e caricare gli obiettivi, assicurati di seguire anche queste best practice per evitare di superare la quota dell'API.

Mostrare gli obiettivi

Per mostrare gli obiettivi di un giocatore, chiama PgsAchievementsClient_showAchievementsUI.

Il seguente snippet di codice mostra come la tua app può visualizzare l'interfaccia utente degli obiettivi predefinita.

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

La seguente immagine mostra un esempio dell'interfaccia utente degli obiettivi predefinita:

Esempio della UI predefinita degli obiettivi
Esempio dell'interfaccia utente degli obiettivi predefinita.