Skip to main content

Leaderboards

Leaderboards are a great way to add a social and competitive element to any game. They’re a fun way to drive competition among your players. The server supports an unlimited number of individual leaderboards with each one as a scoreboard which tracks separate records.

The server has no special requirement on what the score value should represent from your game. A leaderboard is created with a sort order on values. If you’re using lap time or currency in records you’ll want to order the results in asc or desc mode, as preferred. At creation time you must also specify the operator which controls how scores are submitted to the leaderboard: best, set, incr, or decr.

You can use a leaderboard to track any score you like. Some good examples are: highest points, longest survival time, fastest lap time, quickest level completion, and anything else which can be competed over!

Leaderboards are dynamic in the server because they don’t need to be preconfigured like would be needed if you’ve used Google Play Games or Apple Game Center in the past. A leaderboard can be created via server-side code.

Leaderboard object​

Each leaderboard is a collection of records where each record is a ranked score with metadata. A leaderboard is uniquely identified by an ID.

All leaderboard configuration is immutable once created. You should delete the leaderboard and create a new one if you need to change the sort order, operator, reset schedule, or whether it is an authoritative leaderboard or not.

Authoritative leaderboards​

Creating an authoritative leaderboard means that clients will not be able to submit scores directly to the leaderboard, all submissions must be made via the server runtime.

By default leaderboards are not authoritative, meaning that clients can submit scores directly to the leaderboard. You must explicitly set the authoritative flag to true when creating the leaderboard, it cannot be changed later.

Sort order​

Leaderboard records are sorted based on their configured sort order: DESC (default) or ASC. The sort order is decided when a leaderboard is created and cannot be changed later.

Operators​

Configure how leaderboard record scores are set using the following operator values:

  • set - The value will be set to the submitted score
  • best - The value will only be updated if the score being submitted is higher than the existing score
  • incr - The value will be incremented by the score being submitted to it
  • decr - The value will be decreased by the score being submitted to it

The operator cannot be changed after the leaderboard is created.

Reset schedules​

You can assign each leaderboard an optional reset schedule. Records contained in the leaderboard will expire based on this schedule and users will be able to submit new scores for each reset cycle. At the expiry of each reset period the server triggers callbacks with the current leaderboard state. Read about about it Leaderboards Best Practices and see the Tiered Leagues guide for an example use case.

Reset schedules are defined in CRON format when the leaderboard is created. If a leaderboard has no reset schedule set its records will never expire.

Leaderboard records​

Each leaderboard contains a list of records ordered by their scores.

All records belong to an owner. This is usually a user but other objects like a group ID or some other custom ID can be used. Each owner will only have one record per leaderboard. If a leaderboard expires each owner will be able to submit a new score which rolls over.

The score in each record can be updated as the owner progresses. Scores can be updated as often as wanted and can increase or decrease depending on the combination of leaderboard sort order and operator.

Records metadata​

Each record can optionally include additional data about the score or the owner when submitted. The extra fields must be JSON encoded and submitted as the metadata.

An example use case for metadata is info about race conditions in a driving game, such as weather, which can give extra UI hints when users list scores.

    {
      "surface": "wet",
      "timeOfDay": "night",
      "car": "Porsche 918 Spyder"
    }

Create a leaderboard​

A leaderboard can be created via server-side code at startup or within a registered function. The ID given to the leaderboard is used to submit scores to it.

Submit a score​

A user can submit a score to a leaderboard and update it at any time for non-authoritative leaderboards. For authoritative leaderboards, scores can only be submitted using the server runtime functions.

When a score is submitted the leaderboard’s pre-configured sort order and operator determine what effect the operation will have.

The set operator will ensure the leaderboard record always keeps the latest value, even if it is worse than the previous one.

Submitting to a leaderboard with the best operator ensures the record tracks the best value it has seen for that record. For a descending leaderboard this means the highest value, for an ascending one the lowest. If there is no previous value for the record, this behaves like set.

With the incr operator the new value is added to any existing score for that record. If there is no previous value for the record, this behaves like set.

List records​

A user can list records from a leaderboard. This makes it easy to compare scores to other users and see their positions.

Getting the Rank Count

The leaderboard record list result from calling any leaderboard list function includes a RankCount property which provides the total number of ranked records in the specified leaderboard. This is only populated for leaderboards that are part of the rank cache (i.e. are not included in the leaderboard.blacklist_rank_cache configuration property).

List by score​

The standard way to list records is ordered by score based on the sort order in the leaderboard.

You can fetch the next set of results with a cursor.

List by friends​

You can use a bunch of owner IDs to filter the records to only ones owned by those users. This can be used to retrieve only scores belonging to the user’s friends.

List expired records​

Expired records after each leaderboard reset are removed from the leaderboard rankings but they are not deleted. A user can list expired records for their desired time period.

For example, to list records expired in the past week:

List leaderboard records around owner​

Fetch the list of leaderboard records around the owner.