Part 2 - Creating a Leaderboard

By Richard Davey on 6th November 2018   @photonstorm

To create a leaderboard, you first need to login to your App Dashboard within Facebook. Then click the Leaderboards link in the left-hand nav.

You'll see the Create Leaderboard page:

Create a Leaderboard


Give your leaderboard a name. This is a plain string that you will use in your game code to retrieve the leaderboard.

Contextual Leaderboard

Pick if the leaderboard is Contextual or not. Contexts are an important thing to understand in Facebook Instant Games, but essentially it will mean the difference between your leaderboard being global, i.e. shared across all contexts, or specific to a single one.

Score Format - Numeric

Pick the Score Format. There are three options. The first, and default, is Numeric. Use this for a leaderboard where a straight numeric value defines how well a player ranks. The score must be a 64-bit integer. You cannot save floats, however you can display them as if they were, using the offset feature.

With numerical scores you can enter a Decimal Offset. This doesn't change the value that is saved, but it does change the formatted score that comes back from the API. If you enter an offset value of 2 and then save a score value of 1, the scoreFormatted result will be 0.01. A score of 10 will have a formatted value of 0.10, a score of 100 would have 1.00 and so on. This means a value of 12345 would have a formatted value of 123.45.

If you do not wish to use this, you can leave the default offset value of zero, or just don't use the formatted score when displaying them in your game.

Score Format - Time

The second score format is Time. The integer value you pass when saving a score corresponds to milliseconds, so saving a score of 5000 would save a time of 5 seconds. Again, this doesn't change the score value that is saved. That would still be 5000. But the scoreFormatted value would be 00:05.00.

If you save a value of 60,000 it will equate to 1 minute and be formatted as 01:00.00.

If you save a value of 600,000 it will equate to 10 minutes and be formatted as 10:00.00.

If you save a value of 3,600,000, which is 1 hour in milliseconds, it will be formatted as 60:00.00.

Note: The score formatting does not include hours in the display. So, if you were to save 2 hours as a value (7,200,000 milliseconds) it gets formatted as 120:00.00.

Score Format - Custom

The final option is Custom. This works the same way as numeric does, but you can specify a custom string to be appended to the formatted score value in the "Unit" text field. For example, you can set the Unit to be "coin". Then, if you were to save a value of 1, the scoreFormatted value would be 1 coin.

Note that you need to handle localization and plurals yourself. For example, if the Unit is "coin", and you saved a value of 100, you'd likely want it to say "100 coins" in your game. If you set the Unit to "coins", then it would do this, but a score of 1 would display as "1 coins", which doesn't sound correct either.

Equally, if your game is in more than one language, you may want a different unit per language. For example, a German leaderboard may wish it to say "münze" instead of "coin", but there doesn't appear to be any way to handle this in the SDK at the moment.

Negative Scores

Scores can be negative. The maximum value you can pass is a 64-bit signed integer. However, be aware of the sort order when using negative values.

Sort Order

Pick the Sort Order. There are only two options: "Higher is better", or "Lower is better".

With a standard numeric leaderboard, set to "Higher is better", the scores are ranked based on value:

Rank Score
1 3500
2 2000
3 50

With a value of "Lower is better" they rank in reverse:

Rank Score
1 50
2 2000
3 3500

It's important to understand that scores will not save if they are not better than the player's previous score.

So, if a player had a score of 50 in a standard "higher is better" leaderboard, and you tried to save their new score of 40, then the call will fail. It doesn't throw an error, but equally, it doesn't update their old score either. It's just skipped entirely and you get a save event, but the data is all of their old information.

With all of this in mind, click Save to create your leaderboard, and make a note of the name, as you'll need it in your game code.