Services de jeux Play pour C++

Le SDK C++ des services de jeux Google Play fournit une API C++ à utiliser avec les services de jeux Google Play. Il est destiné aux développeurs qui disposent d'une implémentation C++ existante de leur jeu.

Actuellement, le SDK implémente les services suivants:

  • Autorisation
  • Succès
  • Classements
  • Événements
  • Jeux enregistrés
  • Nearby Connections (Android uniquement)
  • Statistiques sur les joueurs

Concepts

De manière générale, pour utiliser le SDK, procédez comme suit:

  1. Configurez une configuration de plate-forme pour Android.
  2. Utilisez un GameServices::Builder pour configurer et créer un objet GameServices. L'objet GameServices tente automatiquement de se connecter et renvoie le résultat via un rappel OnAuthActionFinished(). Notez le résultat renvoyé par le rappel. Si la tentative de connexion automatique a échoué, vous pouvez afficher un bouton permettant aux utilisateurs de se connecter.

  3. Après avoir reçu le résultat OnAuthActionFinished(), vous pouvez utiliser l'objet GameServices et ses gestionnaires enfants pour effectuer des appels de services Play Jeux, y compris:

    • Connexion (après l'échec de l'autorisation): StartAuthorizationUI()
    • Débloquer des succès: Achievements().Unlock()
    • Afficher les succès à l'aide de l'UI intégrée: Achievements().ShowAllUI()
    • Envoyer un meilleur score: Leaderboards().SubmitScore()
    • Se déconnecter: SignOut()

  4. Lorsque vous avez terminé d'utiliser l'objet GameServices, réinitialisez-le ou supprimez-le.

Plus en détail:

  1. Initialiser une configuration de plate-forme: il s'agit d'un objet contenant des informations d'initialisation spécifiques à la plate-forme. Sur Android, la configuration de la plate-forme contient la VM Java et un pointeur vers l'Activity actuelle:

    // 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. Créez un objet GameServices: cet objet est le principal point d'accès aux fonctionnalités des services de jeux Google Play. Les instances GameServices sont créées avec GameServices::Builder.

    Dans la plupart des implémentations, un objet GameServices donné persiste aussi longtemps que votre environnement C. Vous n'avez pas besoin de le réinitialiser lorsque votre Activity Android est mis en pause et repris.

    // 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. Utilisez les classes Manager pour gérer votre objet GameServices. Les gestionnaires sont accessibles à partir d'une instance GameServices et regroupent les fonctionnalités associées. Exemples : les gestionnaires de succès et de classements. Elles ne contiennent pas d'état visible par l'utilisateur. Les gestionnaires sont renvoyés par référence, et l'instance GameServices contenante contrôle leur cycle de vie. Votre client ne doit jamais conserver une référence de gestionnaire. À la place, votre client doit conserver l'instance GameServices.

    Les gestionnaires renvoient des données via des objets de type valeur immuable. Ces valeurs reflètent une vue cohérente des données sous-jacentes au moment de la requête.

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

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

  4. Lorsque vous avez terminé d'utiliser l'objet GameServices, effectuez un nettoyage en appelant reset() sur le unique_ptr qui en est propriétaire ou en laissant le unique_ptr le détruire automatiquement lorsqu'il sort du champ d'application.

Modèle de thread

Sauf indication contraire, toutes les méthodes GameServices et Manager ont des implémentations asynchrones et thread-safe. Elles peuvent être appelées sur n'importe quel thread sans verrouillage externe et s'exécutent dans un ordre conforme à leur ordre d'appel.

Les méthodes d'accès (celles qui lisent l'état) se déclinent en deux variantes principales. Le premier type de méthode (avec des noms comme FetchProperty()) fournit de manière asynchrone ses résultats à un rappel fourni. Le second (avec des noms comme FetchPropertyBlocking()) renvoie de manière synchrone ses résultats au thread appelant.

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

Tous les rappels utilisateur sont appelés sur un thread de rappel dédié. Ce thread est potentiellement distinct de tout concept de plate-forme de "thread principal" ou de "thread UI". Vous devez également vous assurer que les rappels utilisateur s'exécutent rapidement. Un thread de rappel bloqué peut entraîner des problèmes visibles par l'utilisateur (par exemple, l'exécution retardée d'une requête de déconnexion).

Informations spécifiques à la plate-forme

Pour commencer à utiliser le SDK Play Jeux C++ sur Android, consultez le guide de démarrage rapide.

Complément d'informations

Pour en savoir plus, consultez la documentation de la classe fournie avec le SDK C++ des services de jeux Google Play, et les exemples qui montrent comment utiliser le SDK.

Si votre jeu utilise un serveur backend, consultez la page Activer l'accès côté serveur aux services de jeux Google Play.