Android: Google Play Services - Leaderboards

This article explains how to add a leaderboard to your Android game using the Google Play Services extension. Before continuing you should have already set up the extension and be able to log the user in, and if you haven't done that yet then you should read the following article before continuing:

Once you have everything set up you correctly then you are ready to add a leaderboard to your game.


Set Up The Leaderboard

Before you can add any code in your game to deal with leaderboards, you first have to create them from the Google Play Developer Console. In the console, you need to select the Game Services menu item, and then select the game that you want to add leaderboards to:


Once you have selected a game, a new window will show the Game Details, and on the left you can select Leaderboards from the menu:


Selecting that will take you to the leaderboards setup screen. You should now click the button labelled Add Leaderboard:


When you click that button you'll be taken to a new page where you must give the details for the leaderboard, giving it a name, a value type (score, currency or time) as well as supplying an icon and a few other things:


Make sure to write down (or remember) the Name you give to your leaderboard, as you'll need it later in GameMaker Studio 2.

When you are happy with the settings, click Save, and your leaderboard will be given the status "Ready to publish". Once you publish your game, all of your game's leaderboards will be published with it.

IMPORTANT! While your game is not publicly available, you can edit the leaderboard properties, but once the game is published, you will not be able to edit anything.


You want to click on the Continue to next step button now (unless you have already set up achievements - as explained here - in which case you can skip this section and go straight to the GameMaker Studio 2 part). This will take you to the page where you link the game you want to use the leaderboard, and set up tester accounts. First linking your game... You need to click the Linked Apps link, as shown below:


You will be asked to select whether the app is Android or Web, and you want to select Android. In the next section you give the Name of the game, and then select the Package Name from a list of the APKs that you have already uploaded to Google Play:


You then have Multiplayer Settings (these should be switch off) and then the option to use the Google Play anti-piracy measures, which - unless you are using the Google Play Licensing extension - should also be off. When ready, click the Save And Continue button at the top of the page, and you will be shown a confirmation window. GameMaker Studio 2 does not require the Client ID that is shown so simply click the Back to list buitton to go back to the leaderboards page.

At this point, assuming your device is using the same Google account as you are using to publish the game, you don't need to take any further action and can continue to add the leaderboard code into your game. However if your test device(s) are not linked to the developer account, or you wish other people to test the leaderboards, you will need to add a Tester Account. You can find out how to do this from the following Google document:


GameMaker Studio 2

We can go back to GameMaker Studio 2 now and start to add the code to deal with showing the leaderboards. There is essentially only one way to do this, and that's to open the Google Play screen overlay.

To open the Google Play overlay, you would require the following code in the mouse event of a controller object, or a button object (or whatever):

if achievement_available()
    if !achievement_login_status()

The above code uses achievement_available to check and see if the leaderboard API is available, and if it is it calls achievement_show_leaderboards to bring up the Services overlay with the leaderboards. If the leaderboard API isn't available, it checks to see if the player is logged in and if not then it logs the player in.

That covers showing the leaderboard, but what about sending scores to it? For that we need to use the function achievement_post_score:

achievement_post_score("Qrt%645ytt", score);

This will simply post the score to the given leaderboard. Note that the you use the leaderboard ID as a string to identify it, and you can get this ID from the Google Play Developer console (as shown above). You can call this function from any object at any time, and not just a controller.



As you can see, setting up leaderboards is a simple process and requires only a little time to set up and get working. Once you have added the code given above (and set up the developer console) you should be able to run the game from GameMaker Studio 2 on your device and see it log in and be able to post to the leaderboard and open the Play Services overlay.

If you haven't already set up achievements in your game, then take a look at the following article:












Have more questions? Submit a request


Article is closed for comments.