How to Create a Game Leaderboard With a Few Lines of Code

Sebastian SztangierskiSebastian Sztangierski

Tutorial presenting a simple leaderboard in your game powered by Syncano.

Leaderboards in Games

Many game creators use more or less complex leaderboards in their games to make them even more fun and competitive. An example of a well-used leaderboard is a browser-based game called This simple, yet very addictive game uses a simple scoreboard to keep its players involved in the game and to drive them to play more and grow bigger. Every time a player eats a smaller enemy or a ‘food cell’ he grows and gets points, which are calculated and later used to display on a leaderboard the players with the highest score.

alt text

Simple Leaderboard in a Few Steps

So if you are curious about how to create a leaderboard in your app with a minimal effort, I’m happy to introduce you to Syncano. With Syncano as the backend, and the Unity library, we’ll do it in three simple steps.

Note this also can be done in both native Android and iOS platforms with small adjustments.

Step 1: Setting up Syncano

The first thing you need to do is to create a Class that stores a user nickname and score. A Class is actually a schema for a Data Object you will use to store data. A Class can be created using the Dashboard or by API calls. In this example we’ll add a Class using the Dashboard.

  1. Log in to the Dashboard. If you don’t have an account, sign up here
  2. Create a new Instance or select an existing one
  3. Go to the Classes panel located at the top left corner and click the ADD button located at the top right corner
  4. Create a Class named ‘record’ with a schema that matches the screenshot below

alt text Please make sure to check the ‘Order’ checkbox beside the score entry. You can read more about ordering and filtering here.

Step 2: Create a Script and a Script Endpoint

According to Syncano documentation:

A Script is an object that contains code that can be run on Syncano's servers. In our case, we create a Script Snippet that handles processing information and returns to us the top ten players with the highest scores. To create a Script that returns the top ten players to our leaderboard, you must follow the steps below:

  1. Go to the Syncano Dashboard and generate a new API Key with the Ignore ACL flag enabled. Here's a guide on how to create an API Key
  2. In the Dashboard, click on the Scripts element located under Snippets from the left sidebar and click the ADD button at the top right corner
  3. Create a Script named get_top_ten and for Runtime environment select Node.js
  4. Open the get_top_ten Script and paste the code below
 var api_key = "YOUR_API_KEY";  // API key with ignore ACL permission
 var instance_name = "YOUR_INSTANCE_NAME"; // current instance name
 var class_name = "record"; // Data Object Class which holds information about player scores
 var page_size = 10; //we want to return only top 10 players

 var Syncano = require('syncano');  // include Syncano
 var connection = Syncano({apiKey: api_key}); // Syncano object instance
 var DataObject = connection.DataObject; // Data Object we operate on

 var get_top_ten_query = {
       instanceName : instance_name,
       className: class_name

 var orderBy = "-score"; //The default direction of ordering is ascending. If you want to reverse direction of ordering, add a minus sign to the field name.

 DataObject //request 10 objects of record class and order them by highest score
     .then((result) => {
    .catch((error) => { //catch and print error if there is any
        console.log('error', error);

Make sure you set correct Instance name and API Key

So you now have a Script that returns to us the top ten players with the highest scores. The next thing you need to do is to create a Script Endpoint so your application can access the Script you just created. According to Syncano documentation, a Script Endpoint is:

A Script Socket is simply a URL that a website or application can make a HTTP request to. In the case of Syncano, this HTTP request to the URL will cause a Script execution.

So in our case, if our application is to communicate with Syncano and process the data to the leaderboard, we need a URL that runs the Script and returns the data.

  1. Go to the Sockets section located at the top left corner in the Dashboard
  2. Click the ADD button located at the top right corner
    alt text
  3. Create a Script Endpoint named get_top_ten. Set Script to get_top_ten and make this endpoint public.

alt text

  1. Once you have created a Script, copy its URL and save it for later. You will need it when making calls to Syncano from Unity.

alt text

That’s all. Now we need to use the Syncano Unity library in order to process returned data.

Step 3: Syncano Unity Library Usage

The Syncano Unity library was designed to provide a set of core features like handling Data Objects, Script Endpoints, Channels, etc. In our example, we want to increase a player’s score and display it.

Before you start, you need to download and install the Syncano library for Unity. Source code and dll can be downloaded from Syncano Unity Library GitHub. To install the library, you can copy source code straight into your project or download a dll file and place it in the Assets folder.

The next thing we need to do is to create a Record Class, which is the counterpart to the same Class in Syncano.

using Syncano;  
using Newtonsoft.Json;

public class Record : SyncanoObject {

public string Name { get; set; }

public int Score { get; set; }

public Record() { }

public Record(string name, int score) { Name = name; Score = score; }  

Once you have added a Record Class to the Unity project, you need to create an Instance of a Record Class and update it when we want to reward a player and increase the player’s overall score.

using UnityEngine;  
using System.Collections;  
using System.Collections.Generic;  
using Syncano;  
using Syncano.Data;  
using Newtonsoft.Json;

public class LeaderboardExample: MonoBehaviour {

private SyncanoClient syncano;  
private Record record;

IEnumerator Start()  
    syncano = SyncanoClient.Instance.Init("YOUR_API_KEY", "INSTANCE_NAME");
    record = new Record("Test Nickname", 0);
    yield return syncano.Please().Save(record, OnRecordCreated, OnRecordNotCreated);

private void OnRecordCreated(Response<Record> r)  
{ =; // We need to set record id so it can be later updated properly on the Syncano side
    // handle create Record success

private void OnRecordNotCreated(Response<Record> r)  
    // handle Record error

Every method provided by the library can be run synchronously and asynchronously. To call a method synchronously, just add a yield return statement, otherwise the call will be made asynchronously.

From now on, every time you call Save on your Record Object, it will be updated. You can increase or decrease a player’s score whenever you want. It can be done from any place in your project. Just call it like in the code snipped below.

    private void UpdateScore()
        record.Score+= 1;
        syncano.Please().Save(record, OnRecordUpdated, OnRecordUpdateFail);

    private void OnRecordUpdated(Response<Record> r)
        // handle success

    private void OnRecordUpdateFail(Response<Record> r)
        // handle error

The last thing we need to handle is displaying the leaderboard. To retrieve data, we need to call the Script we created earlier. Remember the link to the Script Endpoint you saved before? You will need to provide it when calling the RunScriptEndpointUrl method.

private IEnumerator UpdateLeaderboard()  
        while (true)
            syncano.Please().RunScriptEndpointUrl("URL_TO_SCRIPT_ENDPOINT", ScriptCallback);
            yield return new WaitForSeconds(3);

        yield return null;

The Script will run a callback method after it has received a message from the server. Once it has been received, we need to check if it was successful, and if so, turn the returned JSON into a list of top ten best players records and display them.

    private void ScriptCallback(ScriptEndpoint endpointCallback)
            List<Record> topTenRecords = JsonConvert.DeserializeObject<List<Record>>(endpointCallback.stdout);



    private void DisplayTopScore(List<Record> list)
        Debug.Log("*** TOP SCORE ***");

        for (int i = 0; i < list.Count; i++)
            //Handle UI display
            Debug.Log("*** Nickname: " + list[i].Name + " Score: " + list[i].Score + " ***");

And this is it! With minimal effort, we have created a simple leaderboard for our game. Below, you can find some ideas for how the leaderboard can be improved. You can also download the source code of this article here. Also, if you need a full example with a working game and leaderboard, let us know in comments under this article.

Ideas to Improve Your Leaderboard

Real-time leaderboard refresh with Channels

Instead of calling a Script Endpoint every three seconds, a leaderboard may use the Real-time channel to refresh its data. Thanks to this, a player always has the freshest data.

Inform your users about who got the highest score at the end of the day

Using Schedules, you can inform your users about who was the best player by sending an email at the end of the day/week/month. With Syncano, you can store any kind of data and process it however you want!

Setup Triggers for best players on the leaderboard

With Syncano, you can create a separate leaderboard of the top 10 players ever. Then, you could set up a Trigger to inform a player via email if he has been beaten and fell off the ladder.


Building a leaderboard in Syncano is a pretty straightforward task. All you need to do is to configure a Class for your Data Objects and write a simple Script that returns data. But it is not all that you can do with Syncano! You can easily extend your leaderboard so that it notifies players when they climb up or fall off the ladder, etc. Source code can be found on our Community Github page. If you have any other ideas for how to improve the leaderboard with Syncano, let us know about it on Twitter by tweeting @Syncano.

Also, feel free to ask us any questions you have in the comments under this post, by joining our Slack community channel, or by writing to our support team at [email protected] Good luck!

alt Image Source

Build powerful apps in half the time

Use our serverless platform to set up your backend in minutes.

Learn more