Android: Google Play Services - Achievements

This article explains how to add achievements 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 achievements to your game.

 

Set Up The Achievements

Before you can add any code in your game to deal with achievements, 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 achievements to:

GPServices_SelectGame.png

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

GPServices_AchievementsMenu.jpg

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

GPServices_AddAchievement.png

When you click that button you'll be taken to a new page where you must give the details for the achievement, giving it a name, a description, and supplying an icon:

GPServices_AchievementSetup1.png

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

After giving these details you'll be presented with the following options:

GPServices_AchievementSetup2.png

Here's a brief description of each of the options shown above (their actual values and settings are up to you and will depend on the game):

  • Incremental Achievements: An incremental achievement involves a player making gradual progress towards earning the achievement over a longer period of time, and as the player makes progress towards the incremental achievement, you can report the player's partial progress to the Google Play games services. When checked you will be required to give the number of "steps" required to unlock the achievement.

  • Initial State: Achievements can have three states - hidden, revealed or unlocked. An achievement can never start unlocked, but you can choose here whether it should be hidden or revealed. A hidden achievement means that details about the achievement are hidden from the player and will show a generic placeholder description and icon. A revealed achievement means that the player knows about the achievement, but hasn't earned it yet (and most achievements start in the revealed state).

  • Points: Achievements have a point value associated with them. Points must be assigned values that are a multiple of 5 and a game can never have a total of more than 1000 points for all of its achievements (although it can have less). Note that no single achievement can have more than 200 points assigned to it.

  • List Order: This is the order in which the locked achievements appear when a player views the achievements associated with your game. This can be in any order that you like. Unlocked achievements appear at the top of the list in the order achieved

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

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

GPServices_NewAchievements.png

You want to click on the Continue to next step button now. This will take you to the Leaderboards setup page which we aren't covering in this article so click Continue to next step again (we cover leaderboards here, so if you've already set them up then you can skip the rest of this section and got straight to the GameMaker Studio 2 part, below). This will take you to the page where you link the game you want to use the Achievement, and set up tester accounts. First linking your game... You need to click the Linked Apps link, as shown below:

GPServices_LinkingApp.png

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:

GPServices_AppDetails.png

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 achievements 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 achievements, 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 achievements. 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()
    {
    achievement_show_achievements()
    }
else
    {
    if !achievement_login_status()
        {
        achievement_login();
        }
    }

The above code uses achievement_available to check and see if the achievement API is available, and if it is it calls achievement_show_achievements to bring up the Services overlay with the achievements. If the achievement 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 achievements, but what about if you want to set one? Well, it'll depend on the type of achievement it is, whether it's a single achievement or an incremental achievement. For single achievements you would use the function achievement_post:

achievement_post("ach_CompleteFive", 100);

This will simply set the given achievement to 100%, unlocking it for the user. When calling the function you give the achievement name as a string to identify it, and you can get/set this name 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.

Note that with the Google Services extension, single achievements are either granted or not, so the value here should always be 100. If you want to have an achievement that relates to progress, then you'd make it incremental

To add to an incremental achievement you'd use the function achievement_increment:

achievement_increment("ach_GameCompleted", 1);

The above will add a "step" onto the given achievement. It is worth noting that you do not need to wrap these functions to check if the Play Store is connected, as the Achievements API will store any progress or unlocked achievements for the next time the player logs on.

 

Summary

As you can see, setting up achievements 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 achievements and open the Play Services overlay.

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

 

 

 

 

 

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.