Google Play Games

Google Play Games is a games service primarily used on Android devices. It is a must-have for any Android-capable game.

This article describes how to use GPGS in your Android project, see the GPGS (Desktop) and GPGS (HTML) articles for information about the usage on other platforms.

Overview

Google Play Games belongs to the Google Play services, so you have to get a Google Developer Account and upload your signed APK to the Play Store in order to set it up. It does only work with a correctly signed app then.

Google Play Games supports the following features:

• Achievements
• Leaderboards
• Events
• Cloud save
• Real time and turn based multiplayer

Configure your Play Games project

Configure the project like explained in step 2 of Google's Getting started tutorial.

Note that you should link two applications in step 2.3: "My game" with your signing certificate, and "My game (debug)" with your debug certificate. Otherwise, you won't be able to test GPGS in your debug application.

Usage in your libGDX project

Add the dependency to your Android project:

implementation "de.golfgl.gdxgamesvcs:gdx-gamesvcs-android-gpgs:$gamesvcsVersion"

Note that this dependency declares dependency to play services libraries. You can override the version with Gradle project properties, if needed.

Add the following lines to your AndroidManifest.xml:

<application ...>
    <meta-data android:name="com.google.android.gms.games.APP_ID"
        android:value="@string/app_id" />
    <meta-data android:name="com.google.android.gms.version"
      android:value="@integer/google_play_services_version"/>
    ....
 </application>

Of course then you need to add your App ID from the Developer Console in your res/value/strings.xml:

<string name="app_id">yourAppIdHere</string>

Change your AndroidLauncher to use the GpgsClient and initialize it:

    GdxGame game = new GdxGameSvcsApp();
    game.gsClient = new GpgsClient().initialize(this, false);
    initialize(game, config);

Explicit sign in and sign out

For Google Play Games your game even must provide a sign in/out button to be considered Google Play Games Services-compatible.

If and only if the user clicked this button, you should call logIn() and logOut(). These methods should only be called when the user manually requested an explicit log in/out. On the launch of your game, you must use resumeSession().

Set up mapping when submitting events, scores or unlocking achievements

Unlike implementing API clients for Gamejolt or Newgrounds, GpgsClient does not need a specific setup for submitting events, scores and achievements to the service: You can just call the methods with the the Play Games IDs:

gpgsClient.unlockAchievement("CgkIu46Sr-8fEAIQAw");

However, I would not recommend to do so. Your game should call the interface method with a game service independant string constant for each event, leaderboard and achievement. Of course, your own constant will not work with the Play Games service. You can set a mapping for leaderboard and achievement ids:

gsClient.setGpgsLeaderboardIdMapper(new IGameServiceIdMapper<String>() {
            @Override
            public StringmapToGsId(String independantId) {
                // your mapping here
                return gpgsId;
            }
        })
     .setGpgsAchievementIdMapper(...);

For events, you can override submitEvent() when instantiating GpgsClient.

See sample app's Gpgs branch for a full example.

Cloud save

gdx-gamesvcs-gpgs implementation supports the usage of Google Play Games' powerful cloud save and sync feature. Just call loadGameState() and saveGameState(). Please note that you have to enable this feature both in Google's Developer Console and when calling the initialize method of GpgsClient.

Please note that saved game states are not accessible from GPGS HTML and GPGS desktop. GPGS Android saves game state in snapshots that are only available on Android.