LibGDX Google Play Game Services Tutorial

Google Play Game Services offers cross platform social leaderboards, achievements, and much more (realtime multiplayer, cloud saves, anti-piracy...). I've started implementing google play game services leaderboards and achievements in my LibGDX Android Games, and the purpose of this blog article is to walk through the process so you can do the same!

• I've published an example project on Google Play check it out!
• The example project is freely available on GitHub check that out too!
• You can also get the complete (free) version of Super Jump a Doodle here!

Continue reading after the jump to find out how to add these features to your own games!

Google Play Developer Console Setup

Before we can start making any changes to our app, we first need to work our way through the required developer console setup.

Go to https://play.google.com/apps/publish, and click the Game Services menu option (gamepad icon)

Click 'Add New Game', fill in the required name and category details, then continue

Fill in the required game details, upload the required graphic assets, then continue to linked apps

Link an android app, add your package name (must match your app), then save and continue

Click authorise your app, fill in the package and SHA1, then create client. Note that the SHA1 is presented in eclipse when building your release apk if you are using an up to date version of the eclipse adt plugin. If using an older version of the adt plugin, you can find your certificates SHA1 by running the following shell command “keytool -list -v -keystore ReleaseKey.keystore -keypass android” (note that 'ReleaseKey.keystore' needs to be the full path to your certificate keystore file)

You have to create a minimum of 5 achievements, so go ahead and do so...

Make a note of the IDs, we'll be needing them later

A leaderboard is usually a nice touch, so let's create one of those too

Again, make a note of the ID, we'll need it later

Provided all required fields have been completed, and the required graphic assets uploaded, we can finally publish the Google Play Game Services settings. Do this, and make a note of the App ID, this will be needed later too!

LibGDX App Setup in Eclipse

Copy the BaseGameUtils and google-play-services_lib directories from the example project on GitHub and save them somewhere locally. Now import both these existing projects into Eclipse, right click the project folders in package explorer, properties > android, then tick the “Is Library” box. The libraries should now be available to the other projects in your workspace. Finally, import your LibGDX projects (core, android and desktop).

Right click the android project in package explorer:

• Android, in the Library section Add > BaseGameUtils > OK, Add > google-play-services_lib > OK, Apply.
• Properties > Java Build Path, Projects tab, add both BaseGameUtils and play-game-services_lib projects, then ok twice to save and close.

Open AndroidManifest.xml, and add two permissions:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

You will also need to add the following element as a child to application:
<meta-data android:name="com.google.android.gms.games.APP_ID" android:value="@string/app_id" />

Edit your android project's res/values/strings.xml, add the following element as a child to resources:
<string name="app_id">796047314795</string> 

Note you will need to change the app_id value to whatever your app_id is... The number will have been presented to you in the Google Play Developer Console.

You most likely already have an ActionResolver interface in your core project, if you do, add the Google Play Game Services related methods below. If you don't already use an ActionResolver interface, now's a good time to add one:

package com.theinvader360.tutorial.libgdx.gameservices;

public interface ActionResolver {
  public boolean getSignedInGPGS();
  public void loginGPGS();
  public void submitScoreGPGS(int score);
  public void unlockAchievementGPGS(String achievementId);
  public void getLeaderboardGPGS();
  public void getAchievementsGPGS();
}

Edit your android project's MainActivity. Have it implement GameHelperListener and ActionResolver, and add the unimplemented methods. Add a GameHelper field to the class, and a default constructor that instantiates it. For full detail, take a look at the example project. Note if you're copying this implementation you need to remember to swap the leaderboard ID to the ID in your Google Play Developer Console, personally I prefer to shift all the ID's to a single Constants class, but didn't do that in the example project as I tried keeping it as simple as possible, and with the minimum of change from the standard Super Jumper Demo.

You will also need to add the relevant methods to your Desktop projects ActionResolver mock implementation, again for an example see the example project.

Now all that's left to do is call the relevant ActionResolver methods from your game at appropriate times...

At gameover, for example, you might call the following (remember to swap the ID's to match those in your Google Play Developer Console!):

if (game.actionResolver.getSignedInGPGS()) {
 game.actionResolver.submitScoreGPGS(world.score);
 if (world.score >= 100) game.actionResolver.unlockAchievementGPGS("CgkI6574wJUXEAIQAQ");
 if (world.score >= 200) game.actionResolver.unlockAchievementGPGS("CgkI6574wJUXEAIQAg");
 if (world.score >= 300) game.actionResolver.unlockAchievementGPGS("CgkI6574wJUXEAIQBA");
 if (world.score >= 400) game.actionResolver.unlockAchievementGPGS("CgkI6574wJUXEAIQBQ");
 if (world.score >= 500) game.actionResolver.unlockAchievementGPGS("CgkI6574wJUXEAIQBg");
}

Or on the menu screen you might call:

if (game.actionResolver.getSignedInGPGS()) game.actionResolver.getLeaderboardGPGS();
else game.actionResolver.loginGPGS();

or

if (game.actionResolver.getSignedInGPGS()) game.actionResolver.getAchievementsGPGS();
else game.actionResolver.loginGPGS();


That's all there is to it! Now all you need to do is build your apk (note Google Play Game Services will only work correctly if you build using the same certificate as the one you set in the Developer Console, so do a full release build and manually deploy to your device, don't just right click > run as > android application), drop the apk on your device, install, and play :)

----------

Note it is possible that I may have skipped a little detail in this article. If you have any problems, I would suggest that you follow the first section (Google Play Developer Console Setup), git clone https://github.com/TheInvader360/libgdx-gameservices-tutorial.git, build a release apk, drop it on your device, and have a play. The example project is wide open and should be pretty self explanatory, feel free to use and abuse it in any way you see fit!

----------

Update: If you want to work with the latest version of googleplay game services...

• Using the Android SDK Manager, download the latest API version (API19)
• Replace the old google-play-services_lib directory in workspace root with the new version (available at <android-sdk>/extras/google/google_play_services/libproject/google-play-services_lib).
• Replace the old BaseGameUtils directory in workspace root with the new version from my github project - https://github.com/TheInvader360/libgdx-gameservices-tutorial/tree/master/BaseGameUtils. Alternatively, you can grab the latest version from the eclipse_compat/libraries/BaseGameUtils/ dir of the playgameservices android-samples repository (git clone https://github.com/playgameservices/android-samples.git) but please keep in mind that things change over time so the latest and greatest version might need some code changes on your part to get things working again. Probably easier to stick with the version in my github project if you are following this walkthrough and want an easy life :)
• Delete google-play-services_lib and BaseGameUtils projects from eclipse package explorer, then import existing android code to add the new versions.
• Right click the BaseGameUtils project and on the Android tab tick Is Library, and add reference to google-play-services_lib, apply.
• Right click the libgdx android project and correct the Java Build Path if there is a problem (remove and re-add BaseGameUtils), and again on the Android tab if there is a broken reference to BaseGameUtils, apply.
• Set AndroidManifest minSdkVersion to 9 targetSdkVersion to 19
• Add <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/> as a child of application in AndroidManifest.xml
• Refresh and clean.
• Make these changes to the android project's MainActivity class - https://github.com/TheInvader360/libgdx-gameservices-tutorial/commit/a5c36953b3b51c4f0dd9ea3f8606061cf2ec3fc4