Obiettivi

Questo documento descrive come utilizzare gli obiettivi dei servizi per i giochi di Google Play nei giochi C++. Questo documento presuppone che tu abbia configurato il progetto come descritto in Configurazione dei servizi per i giochi di Google Play. Puoi trovare l'API Achievements in PgsAchievementsClient.

Prima di iniziare

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

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

• Segui le istruzioni per installare e configurare l'app in modo che utilizzi i servizi per i giochi di Play nella guida Configura l'API Google Play Games Services.

• Definisci gli obiettivi che vuoi che il tuo gioco sblocchi o mostri seguendo le istruzioni della guida di Google Play Console.

• Acquisisci familiarità con i consigli descritti nella lista di controllo della qualità.

Ottenere un client di obiettivi

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

Sbloccare obiettivi

Per sbloccare un obiettivo, chiama il metodo PgsAchievementsClient_unlock e passa l'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 PgsAchievementsClient_increment.

Il seguente snippet di codice mostra come la tua app può incrementare 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 lo sblocca automaticamente 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.

Visualizzare 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 predefinita per gli obiettivi.

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'immagine seguente mostra un esempio della UI predefinita degli obiettivi:

Esempio dell'interfaccia utente degli obiettivi predefinita.