Unity Leaderboards


This tutorial takes you through the process of creating a Leaderboard. An Event is also created, which will be used to post scores to the Leaderboard. You'll then see how in Unity:

You don’t need anything extra to follow this tutorial, but if you’d like to see the project you can download it:

Creating the Score Event

The first thing you need to do is create an Event that will push the player’s score to the Leaderboard.

More Details on Events? For an in-depth guide about Events click here.

For this tutorial, your new Event needs one Attribute, which will be the score, and you can call the Event something like Submit Score. The options for creating an Event are as follows:

Creating the Leaderboard

Next you'll need to create your Leaderboard.

1. Navigate to Configurator > Leaderboards.

2. Click Add. The page adjusts for adding a new Leaderboard.

More on Leaderboards? Most of the details you see here can be left as default for this tutorial but you can get more information about Leaderboard configuration here.

3. The important details for us in this example are:

4. Under Fields, click Add to add a Running Total to the Leaderboard:

Testing the Leaderboard

Now you're ready to send some scores to your Leaderboard. However, before you go into Unity, you should test this Leaderboard in the Test Harness:

1. After authenticating yourself as a Player, find your Event under LogEvent, enter a score, and send the Event.

2. Immediately after you send the request, you will see a message appear in the Inspector. This is a NewHighScoreMessage and when you go back into Unity you are going to set up an Event listener to execute some code whenever a player gets this Message:

Getting the Leaderboard Data

You can also check your Leaderboard data entries from the Test Harness using the LeaderboardDataRequest:

Now you're ready to start sending and receiving Leaderboard data in Unity.

Getting the Leaderboard Data in Unity

In the previous tutorial on Cloud Code, you've already seen how to send a LogEventRequest in Unity, which you can check out here. The code is as follows:

new GameSparks.Api.Requests.LogEventRequest().SetEventKey("SUBMIT_SCORE").SetEventAttribute("SCORE", 1234).Send((response) => {
    if (!response.HasErrors) {
        Debug.Log("Score Posted Successfully...");
    } else {
        Debug.Log("Error Posting Score...");

To get the Leaderboard data back, you need to call a LeaderboardDataRequest, the same way you did using the Test Harness:

new GameSparks.Api.Requests.LeaderboardDataRequest().SetLeaderboardShortCode("SCORE_LEADERBOARD").SetEntryCount(100).Send((response) => {
    if (!response.HasErrors) {
        Debug.Log("Found Leaderboard Data...");
        foreach(GameSparks.Api.Responses.LeaderboardDataResponse._LeaderboardData entry in response.Data) {
            int rank = (int) entry.Rank;
            string playerName = entry.UserName;
            string score = entry.JSONData["SCORE"].ToString();
            Debug.Log("Rank:" + rank + " Name:" + playerName + " \n Score:" + score);
    } else {
        Debug.Log("Error Retrieving Leaderboard Data...");

The important thing here is to get the information back out of the Leaderboard Data:

Now, running the Request will print out the details of each of the Leaderboard entries in the console:

Message Listeners

Finally you'll want to hook up the NewHighScoreMessage listener so that you can have some custom code execute when the player receives a new High Score:

void Awake() {
    GameSparks.Api.Messages.NewHighScoreMessage.Listener += HighScoreMessageHandler;
void HighScoreMessageHandler(GameSparks.Api.Messages.NewHighScoreMessage _message) {
    Debug.Log("NEW HIGH SCORE \n " + _message.LeaderboardName);

Now, to test this out, enter a new High Score for your player in the Unity sample project. You should see the NEW HIGH SCORE message appear in the console window: