Achievements unlocked!

Achievements and trophies are available on most platforms today and help build engagement with your players in a few ways. They capture “the moment” for the player when they accomplish something meaningful in the game. And over time, for some players (like the “Achievers” of the Bartle taxonomy) they form a scrapbook, or collection, of sorts that marks their experiences over a variety of games. Finally, they provide another storytelling tool that allows the game designer to guide the user through different approaches to playing the game and exploring the game world, perhaps in ways that might not be obvious—completing a level in a very short time, or only using a certain weapon. 

In our previous installment, we spent quite a bit of time working through setting up leaderboards for your game. Let’s build on that by adding GameCircle Achievements and give your players some goals to strive for.

Figure 1 - GameCircle Achievements User Experience on Fire TV showing an unlocked achievement on the left

and a locked achievement on the right

Setting up Achievements

As with leaderboards, you first need to have your game set up on the Amazon Developer Portal and configure GameCircle for it. Each GameCircle configuration can have up to 100 achievements. Even if you want to provide a lot of achievements, it’s a good idea to hold some of that 100 in reserve so you can add additional achievements as you expand the content of your game with updates over time.

When you are signed in to the Developer Portal, click on “Apps & Services” and then click on the “GameCircle” link, highlighted with the blue box, below.

Figure 2 - Starting the GameCircle configuration

Just as with leaderboards, since you have already done the initial set up of GameCircle, you’ll see something like this:

Figure 3 - GameCircle configurations

Click on the “0 draft / 0 published” text under “Achievements”. This will display the “Add achievements” step. Click on the “Add an achievement” button, highlighted in blue in the picture below:

Figure 4 - Achievements step in GameCircle configuration

This will display the “Create achievement” pop-up.

Figure 5 - Create achievement pop-up

I’ll describe each of these in the order they appear in the pop-up.

Achievement ID: Required. Like the Leaderboard ID, this is how you will refer to the achievement in your code. I use the naming convention “ACHIEVEMENT_” and then a description, such as “ACHIEVEMENT_BUSTIN_ROCKS”. You can use what works for you as long as it is upper or lowercase letters, numbers or underscores with no spaces or other characters. This ID is not visible to your players. Once you save your leaderboard, even as a draft, you will not be able to change the Achievement ID.

Title: Required. This is the name your players will see.

Hide until earned: Required. This allows you to keep an achievement totally hidden from the player. Use this if you want to surprise the player without showing the locked achievement in the list the player can see.

Achievement XP: Required. This represents a score as part of the GameCircle achievement system that comes with this achievement. It is not related to the score inside your game and represents the accumulated player experience across all GameCircle games over time. A single GameCircle configuration can have up to 1500 XP. As with the limit of 100 achievements, it’s wise to hold back some of the points for future expansion. Each achievement may award up to 100 XP. In general, the XP value of an achievement should correspond to the difficulty in unlocking it.

Locked and Unlocked Achievement icons: Required. This is what the player will see in the achievements list before the item is unlocked. I simply start with the unlocked icon and then adjust the brightness, contrast and color to wash out the locked icon. The icons must be 512 x 512 pixel PNG files with no transparency. The file names cannot contain spaces or special characters. As described in the Achievements documentation, a circular mask will be applied to the square images you upload.

Figure 6 - Example of locked (left) and unlocked (center) and masked (right) achievement icons

Locked Achievement description: Required. This is the description the player sees when the achievement is locked. You can use this to tell the player how to unlock it—for example, “Destroy 25 large asteroids in a single game.”

Unlocked Achievement description: Required. This is the description the player will see after they’ve unlocked the achievement. You can use this to adjust the wording to the past tense—for example, “Destroyed 25 large asteroids in a single game.”

Figure 7 – Achievement Icon, Title and Description as the player will see them

As with leaderboards, when initially creating an achievement, you are creating the U.S. English text. You can add additional translations after you save your draft achievement. As you recall from setting up leaderboards, a draft is only accessible to the GameCircle users you define as “Test Accounts”, and that process is described in the section “Testing, Testing…is this thing on” leaderboards blog post. When you are ready to publish your achievements, remember to reset the achievement data as described in the Test Your Game documentation topic.

You can rearrange your achievements by hovering over the number in the list and dragging it up or down. While achievements can be unlocked in any order, it is a good practice to arrange them in the order you would expect a player to earn them. This order will be used by the GameCircle User Experience to indicate the next achievement the player should try to unlock and this ordering provides another way to guide the player through your game experience.

Figure 8 - Next achievement shown in GameCircle UX

Adding Achievements support in your code

That was a long explanation, but I promise the configuration really isn’t difficult or time consuming in actual practice. Now we need to connect your leaderboard to your game—which is actually really simple. 

As discussed in the previous blog post about configuring GameCircle, you need to initialize GameCircle with the features your game will be using. So if you were using Leaderboards and Achievements, your initialization line would look like:

AmazonGameCircle_InitFeatures(AmazonGameCircle_Achievements |
  AmazonGameCircle_Leaderboards);

It is best to put the InitFeatures function call very early in your game initialization, and it should only be called once.

When this InitFeatures line executes, your player will see a pop-up notification that tells them the game is using GameCircle and what features it is using. In this example, the game has initialized Leaderboards, Achievements and Whispersync—indicated by the three icons from left to right.

Figure 9 - GameCircle Initialization notification

As with leaderboards, you’ll need to add some code in a code block on the “Create event” of an object. I use my game controller object called objState, but you can use whatever object is convenient:

// GameCircle Player Info
global.OurName="_";
global.playerid = "-2";
global.avatarURL= "";
global.avatarSprite = -1;

// GameCircle Achievements Info
global.ach_num = 0;
global.ach_dateunlocked[0] = "";
global.ach_description[0] = "";
global.ach_id[0] = "";
global.ach_imageurl[0] = "";     
global.ach_pointvalue[0] = 0;           
global.ach_position[0] = 0;     
global.ach_progress[0] = 0;
global.ach_title[0] = "";
global.ach_is_hidden[0] = 0;
global.ach_is_unlocked[0] = 0;
global.ach_sprite[0] = -1;

As with leaderboards, you need to add an Asynchronous Social event and add this code to that event:

var ident = ds_map_find_value(async_load, "id" );

if(ident == achievement_our_info)
{
    var name = ds_map_find_value(async_load, "name" );
    if(name!=global.OurName)
    {
        global.OurName = name;
        global.playerid = ds_map_find_value(async_load, "playerid" );
        global.avatarURL = ds_map_find_value(async_load, "avatar_url" );
        global.avatarSprite = sprite_add(global.avatarURL,0,0,0,0,0);
    }
}

else if(ident == achievement_achievement_info)
{
    global.ach_num = ds_map_find_value(async_load, "ach_num" );
    
    for(var i=0;i

As you look at this code, you see that there are some interesting things you can do with achievements in your code. You can show the achievement icons and text in your own user interface, but none of that is necessary just to use achievements in a basic way, as you see with most games that use GameCircle.

Granting achievements

After all this setup, now it’s time to give our players credit for doing something amazing!

To grant an achievement, we use the AmazonGameCircle_AchievementProgress function. Of course, to give credit for anything, we first need to be tracking something. For example, in Retroids, if the player destroys 25 large asteroids in a single game, they unlock the “Bustin’ Rocks” achievement. To do this, I have a global variable Achievement_BigAsteroidsHit. I increment that variable each time a large asteroid is hit by a player’s shot. Some achievements require more complex tracking, but whatever you are tracking, you’ll need to write the code to do that. (For more about designing achievements, check out Greg McClanahan’s Achievement Design 101 on Gamasutra.)

You’ll notice that the AmazonGameCircle_AchievementProgress function accepts the achievement ID and a percentage of progress. To simply unlock the achievement completely, pass 100—as in 100 percent—for the percentage of progress.

If you want to have an achievement that potentially goes across multiple play sessions, such as playing 50 games, you could keep track of the count yourself, persisting the count in some way between play sessions and then trigger the achievement when they player reaches that milestone. Or, you could simply have GameCircle keep track of it for you by passing the appropriate percentage complete after each game—which would be 2 for our 50 games example. This means that even if a player plays 25 games on their Fire TV and 10 on their tablet and 15 on their phone, they’ll still get the achievement when they hit 50 total.

When an achievement is earned, a notification pops up to congratulate the player.

Figure 10 – Achievement notification

Achievements can bring a new dimension to your gameplay, build a relationship between your players and your game and guide players to explore your content in new ways.

Go build stuff!

This completes our look at bringing Retroids to Amazon Appstore with GameMaker:Studio. Along the way, we’ve added support for controllers and remote controls, in-app purchasing and GameCircle. Stay tuned to the Developer Blog to learn more about Appstore offerings like Amazon Underground and Merch that can help you build grow the audience for your games and drive player engagement.

Now it’s your turn to go build your fun games for Amazon Fire TV, Fire tablets and other Android devices using Amazon Appstore. I can’t wait to see what you come up with!