Take me to your leader…board!

Now that we have GameCircle set up and Whispersync working, it’s time to bring out the competitive instincts of our players with leaderboards. Leaderboards are a staple in the gaming landscape and allow players to compare their scores with all the other people who have played the game today, this week, or ever. Depending on the nature of your game, you can have multiple leaderboards. Retroids has an overall leaderboard, as well as separate leaderboards for each type of control—touch, game controller or Amazon Fire TV remote control—to allow players to compare themselves against people who play the way they do. For another type of game, you might have just a single, overall leaderboard or leaderboards based on level, character class, or whatever makes sense.

Figure 1 - List of leaderboards in Retroids and the Top Scores leaderboard

Setting up leaderboards

Unlike Whispersync, you need to do a little configuration on the Amazon Developer Portal before you can use them. Never fear, the set up work is very easy, but first you need to create your title in the developer portal. You don’t need to publish it or even upload an APK to continue on to the rest of the set up steps. Refer back to the earlier post in this series to set up GameCircle if you haven’t already done that.

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

Since you have already done the initial set up for GameCircle, you’ll see something like this:

Figure 3 - GameCircle configurations

We’ll come back to Achievements in our next installment, but for now, click on the “0 draft / 0 published” text under “Leaderboards”. This will display the “Add Leaderboards” step. Click on the “Add Leaderboard” button, highlighted in blue in the picture below:

Figure 4 - Leaderboards step in GameCircle configuration

This will display the “Create New Leaderboard” pop-up.

Figure 5 - Create New Leaderboard pop-up

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

Leaderboard ID: Required. This is how you will refer to the leaderboard in your code. I use the naming convention “LEADERBOARD_” and then a description, such as “LEADERBOARD_ALL”. 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 people playing your game. Once you save your leaderboard, even as a draft, you will not be able to change the Leaderboard ID.

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

Description: Required. This is the description of the leaderboard that will be visible to your players. The description should be a clear description of what this leaderboard is about.

Icon: Required. This is a 512x512 pixel PNG file that will be visible to your players. You can use a different icon for each leaderboard or you can just use the same image for all of your leaderboards. The filename for the icon you upload cannot contain spaces or special characters, even if your computer operating system will allow it. After your icon is uploaded, it will automatically be overlayed with a template that rounds the corners.

Figure 6 - Icon, Title and Description as the player will see them

Score Units: Required. This indicates what the number corresponds to. Usually this is points, but it could be “dollars”, “miles”, “kills” or whatever makes sense for your game and this leaderboard. If you were building a driving game, you could have one leaderboard for races won, with “wins” as the unit, and another for distance driven, with “miles” or “kilometers” as the unit. It usually makes sense for this to start with a lowercase letter since it will be displayed following the number, as shown below.

Figure 7 - Score Units as the player will see it

Score Threshold: Optional. This is a value, above which no value will be added to the leaderboard. This is usually used as a form of cheat protection. If you feel the highest realistic score is 1,000,000 points, you could set this at that value and any score above that will just be ignored. Be judicious with this as players who value leaderboard position will definitely not want their valid score ignored. For Retroids, I did not specify a threshold.

Sort Order: Required. This allows you to determine whether the scores are listed highest first or lowest first. Typically in a game, it would be highest first, but if you had a golf game or a game based on times where a lower number is better, you’d use “Lowest scores first”.

Note that when you create a leaderboard initially, you are creating the U.S. English text. You will be able to add translations for additional languages after you click the “Save” button to create your draft leaderboard. A draft leaderboard is only accessible to the GameCircle users you define as “Test Accounts”, which we’ll talk about in a moment. You can create up to a maximum of 50 leaderboards—but that is probably many more than you need to provide a good experiences for your players. When you have multiple leaderboards, you can rearrange them by hovering over the number in the list of leaderboards and dragging them up or down. Make sure your first leaderboard is the one that best represents the primary experience of your game.

Figure 8 - List of Retroids leaderboards

Testing, testing…is this thing on?

To test your draft leaderboards, you will need to set up some test accounts. You will need the GameCircle name of the accounts you are using to test the leaderboards. Finding the GameCircle account name is easy on an Amazon tablet. Just tap on the “Games” tab across the top of the home screen. On a non-Amazon Android device, the test user will need to install one of the many GameCircle games from the Amazon Appstore and tap on the GameCircle sign-in notification when the game starts to see their GameCircle account name. Account names can be changed by clicking the “Edit” button.

Enter these Test Accounts by clicking on the “Test Accounts” step of the GameCircle configuration and typing the GameCircle names where you see the text “Add a player Account” and click the “add” button.

Once the leaderboard is published, the test accounts are no longer needed as the leaderboard will be available to any user. For more information, including how to clear test data from the leaderboards before you publish them, see the Test Your Game documentation topic.

Figure 9 - Entering test accounts

Light at the end of the tunnel—how to use the leaderboard from your game

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. 

You’ll also need to use the information presented in the prior installment to ensure your AmazonGameCircle_InitFeatures function call includes AmazonGameCircle_Leaderboards. If you are using Leaderboards and Achievements, your initialization line will look like:

AmazonGameCircle_InitFeatures(AmazonGameCircle_Achievements |
  AmazonGameCircle_Leaderboards);

You will need an object that will remain active at all times when your game is active. I find a game or state controller object is a convenient place to put this. If you don’t have such an object, just create one without a sprite and add it to your game room. In Retroids, I have a controller object I call objState.

In this object, add this code to the “Create” event:

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

// GameCircle Leaderboard Info
global.lb_name = "";
global.lb_text = "";
global.lb_id = "";
global.lb_numscores = 0;
global.lb_url = "";    
global.lb_sprite = -1;  
global.lb_score[0] = 0;
global.lb_rank[0] = 0;
global.lb_playeralias[0] = "bob";
global.lb_playerid[0] = "";       
global.lb_avatar_url[0] = "";       
global.lb_avatar_sprite[0] = -1;

GameMaker: Studio uses asynchronous events to handle callbacks from APIs like GameCircle. In the same object, add an Asynchronous Social event and add this code to that event:

var ident = ds_map_find_value(async_load, "id" );
if(ident == achievement_leaderboard_info)
{
    global.lb_name = ds_map_find_value(async_load, "lb_name" );
    global.lb_text = ds_map_find_value(async_load, "lb_text" );
    global.lb_id = ds_map_find_value(async_load, "lb_id" );
    global.lb_numscores = ds_map_find_value(async_load, "lb_numscores" );
    global.lb_url = ds_map_find_value(async_load, "lb_url" );    
    
    global.lb_sprite = sprite_add(global.lb_url,0,0,0,0,0);
    for(var i=0;i

Now, after all of this setup, all that remains is actually posting scores to the leaderboard. You’ll do this with the AmazonGameCircle_PostLeaderboardScore function from the extension using the Leaderboard ID you picked when you created the leaderboard. In Retroids, I use this block of code after a game ends:

AmazonGameCircle_PostLeaderboardScore("LEADERBOARD_FULL", score);
    if (CONTROL_REMOTE)
        AmazonGameCircle_PostLeaderboardScore("LEADERBOARD_REMOTE", score);
    else if (CONTROL_GAMEPAD)
        AmazonGameCircle_PostLeaderboardScore("LEADERBOARD_GAMEPAD", score);
    else // must be touch
        AmazonGameCircle_PostLeaderboardScore("LEADERBOARD_TOUCH", score);

Note that you don’t need to worry about whether the player’s score warrants a position on the leaderboard or what that position should be. You just post every score and GameCircle handles all those details for you.

You now have leaderboards working in your game, which definitely makes the game feel more professional and gives your players a great competitive outlet to keep them engaged. As a side benefit, you can keep an eye on the leaderboards, even without other analytics, to get a feeling for how many people are playing every day and player engagement over time.

In our next installment, we’ll finish off our work with GameCircle by adding another great engagement tool to your game: achievements.

Miss the first seven parts of the Building Retroids with GameMaker blog series?

Part 1: Studio

Part 2: Basic Controller Detection

Part 3: Handling Controllers

Part 4: Fire TV Remote and Controller Selection

Part 5: Implementing Amazon In-App Purchasing

Part 6: Implementing GameCircle

Part 7: Implementing Whispersync for Games