How to Create and Use a Leaderboard

In this tutorial, we follow an example of how to create and use a Leaderboard. We'll:

Creating an Event

In this section we'll use the Configurator to create an Event with an Attribute that becomes a System Generated Running Total - this allows your game code to post player scores into the GameSparks platform and have the platform store the highest score for each player.

1. Go to Configurator > Events.

2. Click to Add a new Event. The Add Event page opens.

3. Enter the details for the new Event:

4. In the Attributes panel, click to Add a new Attribute to the Event.

5. Now fill in the Event Attribute details:

Event Attributes as Running Totals? Leaderboards are driven by Running Totals. Any Events that you create with an Attribute which doesn't have Default Aggregation Type set to Used in Script become System Generated Running Total and will appear for selection as a Running Total when you configure a Leaderboard. (You can learn more about Running Totals here.)

6. Click to Save and Close the new Event.

Creating a Leaderboard

In this section we'll create a Leaderboard which arranges all the players' scores in order from highest to lowest.

1. Start by going to Configurator > Leaderboards.

2. Click to Add a new Leaderboard. The Add Leaderboard page opens:

3. Enter the Leaderboard details:

Other Configuration Options? For our example, you can leave the other Leaderboard options at their default settings.

4. In the Fields panel, click to Add a Running Total to the Leaderboard:

5. Now fill in the Running Total details.

6. Click to Save and Close the new Leaderboard.

IMPORTANT - Leaderboard entries will be lost for updated Leaderboards! If you edit a Leaderboard that has had entries posted to it, these entries will be lost when you save your editing changes and update the Leaderboard's configuration.

Testing the High Score Leaderboard and Event in the Test Harness

In this section we'll:

Registering Test Players

1. Go to the Test Harness section and select RegistrationRequest from the Authentication menu and change the userName and displayName as shown below.

2. To send this JSON request to the GameSparks platform, click Send Request. The Inspector shows:

Repeat the registration step for four additional users.

Authenticating a Test Player

Now we'll authorize our first Player: player_first.

1. Select the AuthenticationRequest from the Authentication menu and change the userName to player_first as shown below.

2. To send this JSON request to the GameSparks platform, click Send Request. The Inspector shows:

Posting a Score to the Leaderboard

1. To log a score for our first Player, under Requests click Log Event and then select SCORE_EVT - this is the Event you created above. Notice that the Short Code of the Event Attribute that we chose earlier, SCORE_ATTR, has been inserted as one of the keys in the JSON request.

2. Change the value to 110 as shown and click Send Request. This will register a score of 110 for the first Player:

Note that as well as the request and response shown in the Inspector that there is also an asynchronous NewHighScoreMessage (in yellow text):

3. Now repeat the Authorization and Log Event step for the other four users that you registered. Use an increasing score for each user, for example, 210 for the second Player, 310 for the third Player, and so on.

Retrieving Leaderboard Data

1. To view the Leaderboard, select LeaderboardDataRequest from the Leaderboards menu.

2. Change the leaderboardShortCode in the JSON request to HIGH_SCORE_LB, which is the Short Code that you used when you created the Leaderboard:

3. Click Send Request. The response message can be seen in the Inspector and should contain entries for all five users that you logged Score Events for in the previous steps along with their ranks.

To control the number of entries returned by the LeaderBoardDataRequest, set the entryCount field to the required value. Also, to view a different part of the Leaderboard, set the offset field. The offset is relative to the top-ranked position in the Leaderboard.

If the current authorized player was linked to their Facebook account in the GameSparks platform and they had friends who had logged scores in this game, then setting the social field value to true would return Leaderboard data containing just the player and player's friends:

Getting Players "Around Me"

1. Authenticate the third Player (go to Authentication > AuthenticationRequest and then change the userName in the JSON request to Third Player).

2. Next, under Requests click Leaderboards and then select AroundMeLeaderboardRequest.

3. In the JSON request, set the count field to 1 to show the Leaderboard entries either side of the third Player (the currently authorized player). Notice that the player's rank and score are included in the response:

If you were to authenticate the first Player and repeat the AroundMeLeaderboardRequest, the response would only include two entries. This is because the first Player is at the bottom of the Leaderboard so only the player one rank higher than this Player is shown in the response.