Play-Spieldienste für C++

Das C++ SDK für Google Play-Spieldienste bietet eine C++ API für die Verwendung mit Google Play-Spieldiensten und richtet sich an Entwickler, die bereits eine C++-Implementierung ihres Spiels haben.

Derzeit werden im SDK die folgenden Dienste implementiert:

  • Autorisierung
  • Erfolge
  • Bestenlisten
  • Ereignisse
  • Gespeicherte Spiele
  • Nearby Connections (nur Android)
  • Spielerstatistiken

Konzepte

So verwenden Sie das SDK:

  1. Richten Sie eine Plattformkonfiguration für Android ein.
  2. Mit einem GameServices::Builder können Sie ein GameServices-Objekt konfigurieren und erstellen. Das GameServices-Objekt versucht automatisch, sich anzumelden, und gibt das Ergebnis über einen OnAuthActionFinished()-Callback zurück. Notieren Sie sich das vom Callback zurückgegebene Ergebnis. Wenn der automatische Anmeldeversuch fehlgeschlagen ist, können Sie eine Schaltfläche anzeigen, über die sich Nutzer anmelden können.

  3. Nachdem Sie das OnAuthActionFinished()-Ergebnis erhalten haben, können Sie das GameServices-Objekt und seine untergeordneten Manager verwenden, um Play Spiele-Dienste aufzurufen, darunter:

    • Anmeldung (nach fehlgeschlagener Autorisierung): StartAuthorizationUI()
    • Erfolge freischalten: Achievements().Unlock()
    • Erfolge über die integrierte Benutzeroberfläche anzeigen: Achievements().ShowAllUI()
    • Highscore einreichen: Leaderboards().SubmitScore()
    • Abmelden: SignOut()

  4. Wenn Sie das GameServices-Objekt nicht mehr verwenden, setzen Sie es zurück oder löschen Sie es.

Im Detail:

  1. Plattformkonfiguration initialisieren: Dies ist ein Objekt, das platformspezifische Informationen zur Initialisierung enthält. Unter Android enthält die Plattformkonfiguration die Java-VM und einen Verweis auf die aktuelle Activity:

    // In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);

  2. GameServices-Objekt erstellen: Dieses Objekt ist der Haupteinstiegspunkt für die Funktionen der Google Play-Spieldienste. GameServices-Instanzen werden mit GameServices::Builder erstellt.

    In den meisten Implementierungen bleibt ein bestimmtes GameServices-Objekt so lange erhalten, wie die C-Umgebung aktiv ist. Sie müssen es nicht neu initialisieren, wenn Ihre Android-Activity-Anwendung angehalten und fortgesetzt wird.

    // Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
        .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
        .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
            is_auth_in_progress_ = true;
            started_callback(op);
        })
        .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                     gpg::AuthStatus status) {
            LOGI("Sign in finished with a result of %d", status);
            is_auth_in_progress_ = false;
            finished_callback(op, status);
        })
        .Create(pc);

  3. Verwenden Sie die Manager-Klassen, um Ihr GameServices-Objekt zu verwalten. Auf Manager wird über eine GameServices-Instanz und gruppierte Funktionen gemeinsam zugegriffen. Beispiele hierfür sind die Tools für Erfolge und Bestenlisten. Sie enthalten selbst keine für Nutzer sichtbaren Status. Manager werden per Verweis zurückgegeben und deren Lebenszyklus wird von der enthaltenden GameServices-Instanz gesteuert. Dein Kunde sollte niemals eine Managerreferenz haben. Stattdessen sollte Ihr Kunde die GameServices-Instanz beibehalten.

    Manager geben Daten über Objekte mit unveränderlichen Werten zurück. Diese Werte spiegeln eine konsistente Ansicht der zugrunde liegenden Daten zum Zeitpunkt der Abfrage wider.

    // Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);

// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();

  4. Wenn Sie das GameServices-Objekt nicht mehr benötigen, bereinigen Sie die Ressourcen, indem Sie reset() auf das unique_ptr-Objekt mit dem Eigentümer des Objekts aufrufen oder das unique_ptr-Objekt automatisch löschen lassen, wenn es nicht mehr im Gültigkeitsbereich ist.

Thread-Modell

Sofern nicht anders angegeben, haben alle GameServices- und Managermethoden threadsichere, asynchrone Implementierungen. Sie können ohne externe Sperrung in jedem Thread aufgerufen werden und werden in der Reihenfolge ihrer Aufrufe ausgeführt.

Es gibt zwei Hauptvarianten von Zugriffsmethoden (Methoden, die den Status lesen). Der erste Methodentyp (mit Namen wie FetchProperty()) stellt seine Ergebnisse asynchron einem bereitgestellten Callback zur Verfügung. Der zweite (mit Namen wie FetchPropertyBlocking()) gibt seine Ergebnisse synchron an den aufrufenden Thread zurück.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Alle Nutzer-Callbacks werden in einem speziellen Callback-Thread aufgerufen. Dieser Thread unterscheidet sich möglicherweise von jedem Plattformkonzept eines „Hauptthreads“ oder „UI-Threads“. Außerdem sollten Sie darauf achten, dass Nutzer-Callbacks schnell ausgeführt werden. Ein stehengebliebener Callback-Thread kann zu für Nutzer sichtbaren Problemen führen, z. B. zu einer verzögerten Ausführung einer Abmeldeanfrage.

Plattformspezifische Informationen

Wenn Sie mit der Verwendung des Play Games C++ SDK auf Android beginnen möchten, fahren Sie mit der Kurzanleitung fort.

Weitere Informationen

Weitere Informationen finden Sie in der Klassendokumentation im C++ SDK für die Google Play-Spieldienste. Außerdem können Sie sich die Beispiele ansehen, die die Verwendung des SDK veranschaulichen.

Wenn Ihr Spiel einen Back-End-Server verwendet, lesen Sie den Hilfeartikel Serverseitigen Zugriff auf die Google Play-Spieldienste aktivieren.