Logros

En este documento, se describe cómo usar los logros de los Servicios de juego de Google Play en los juegos de C++. En este documento, se supone que configuraste tu proyecto como se describe en Cómo configurar los Servicios de Google Play Games. Puedes encontrar la API de logros en la PgsAchievementsClient.

Antes de comenzar

Si aún no lo hiciste, puede resultarte útil consultar los conceptos de logros en los juegos.

Antes de comenzar a programar con la API de logros, haz lo siguiente:

Cómo obtener un cliente de logros

Para comenzar a usar la API de logros, primero el juego debe obtener un objeto PgsAchievementsClient. Para ello, llama al PgsAchievementsClient_create método y pasa la actividad.

Cómo desbloquear los logros

Si deseas desbloquear un logro, llama al PgsAchievementsClient_unlock método y pasa el PgsAchievementsClient y el ID del logro.

En el siguiente fragmento de código, se muestra cómo tu app puede desbloquear logros:

// 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 el logro es de tipo incremental (es decir, se requieren varios pasos para desbloquearlo), llama a PgsAchievementsClient_increment en su lugar.

En el siguiente fragmento de código, se muestra cómo la app puede aumentar el rendimiento del jugador:

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

No es necesario que escribas código adicional para desbloquear el logro. Los Servicios de Google Play Games lo desbloquearán automáticamente cuando se alcance la cantidad de pasos necesarios.

Una práctica recomendada consiste en definir el ID de los logros en el archivo strings.xml, de modo que el juego pueda hacer referencia a los logros por ID de recurso. Cuando realices llamadas para actualizar y cargar logros, asegúrate de seguir también estas prácticas recomendadas para evitar exceder tu cuota de API.

Cómo mostrar los logros

Si deseas mostrar los logros de un jugador, llama a PgsAchievementsClient_showAchievementsUI.

En el siguiente fragmento de código, se muestra cómo la app puede mostrar la interfaz de usuario predeterminada de logros.

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

En la siguiente imagen, se muestra un ejemplo de la IU predeterminada de logros:

Ejemplo de la IU predeterminada de logros
Ejemplo de la IU predeterminada de logros.