Erfolge

In diesem Dokument wird beschrieben, wie Sie Google Play Games-Dienste-Erfolge in C++-Spielen verwenden. In diesem Dokument wird davon ausgegangen, dass Sie Ihr Projekt wie unter Google Play Games-Dienste einrichten beschrieben eingerichtet haben. Die Achievements API finden Sie in der PgsAchievementsClient.

Hinweis

Wir empfehlen Ihnen, sich mit den Konzepten für Erfolge vertraut zu machen, sofern Sie dies nicht schon getan haben.

Bevor Sie mit dem Programmieren mit der Achievements API beginnen, sollten Sie Folgendes tun:

• Folgen Sie der Anleitung zum Installieren und Einrichten Ihrer App für die Verwendung der Play-Spieldienste im Leitfaden Play-Spieldienste einrichten.

• Definieren Sie die Erfolge, die in Ihrem Spiel freigeschaltet oder angezeigt werden sollen, indem Sie dem Leitfaden für die Google Play Console folgen.

• Machen Sie sich mit den Empfehlungen der Qualitätscheckliste vertraut.

Achievements-Client abrufen

Bevor Sie die Achievements API verwenden können, muss Ihr Spiel zuerst ein PgsAchievementsClient-Objekt abrufen. Rufen Sie dazu die Methode PgsAchievementsClient_create auf und übergeben Sie die Aktivität.

Erfolge freischalten

Rufen Sie die Methode PgsAchievementsClient_unlock auf und übergeben Sie die PgsAchievementsClient und die Erfolgs-ID, um einen Erfolg freizuschalten.

Das folgende Code-Snippet zeigt, wie Ihre App Erfolge freischalten kann:

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

Wenn der Erfolg vom Typ inkrementell ist (d. h. mehrere Schritte zum Freischalten erforderlich sind), rufen Sie stattdessen PgsAchievementsClient_increment auf.

Das folgende Code-Snippet zeigt, wie Ihre App die Errungenschaft des Spielers erhöhen kann:

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

Sie müssen keinen zusätzlichen Code schreiben, um den Erfolg freizuschalten. Google Play-Spieldienste schalten den Erfolg automatisch frei, sobald die erforderliche Anzahl von Schritten erreicht ist.

Es empfiehlt sich, die Erfolgs-IDs in der Datei strings.xml zu definieren, damit in Ihrem Spiel anhand der Ressourcen-ID auf die Erfolge verwiesen werden kann. Wenn Sie Aufrufe zum Aktualisieren und Laden von Erfolgen ausführen, sollten Sie auch diese Best Practices befolgen, um zu vermeiden, dass Ihr API-Kontingent überschritten wird.

Erfolge anzeigen

Rufen Sie PgsAchievementsClient_showAchievementsUI auf, um die Erfolge eines Spielers aufzurufen.

Das folgende Code-Snippet zeigt, wie Ihre App die Standard-Benutzeroberfläche für Erfolge anzeigen kann.

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

Das folgende Bild zeigt ein Beispiel für die standardmäßige UI für Erfolge:

Beispiel für die Standard-UI für Erfolge.