# Leaderboards

## Description

Leaderboards are where you record and/or retrieve your player rankings and scores. There are different types of leaderboards that offer different features, but they all track your players' scores.

## Time spans

One thing to note about leaderboards is that they track scores for several different time spans. This allows you to use the same leaderboard to track rankings for various time spans. The currently supported time spans are as follows:

* `all-time`
* `daily`
* `monthly`
* `weekly`
* `yearly`

Whenever a score is recorded, it is recorded for each of the aforementioned timespans. So, when a score is recorded, the all-time time span for the leaderboard is updated, as are the daily, weekly, monthly, and yearly time spans for the leaderboard for the specific day, week, month, and year that correspond to the recording's date/time.

This powerful feature allows you to easily retrieve and display rankings for any given day, week, month, or year for which scores have been recorded as well as the all-time rankings.

{% hint style="info" %}
If no scores have been recorded for a given time-span, then an empty set of leaderboard rankings will be returned.
{% endhint %}

## Properties

Leaderboards have the following properties:

| Name                |  Type  |      Default     |
| ------------------- | :----: | :--------------: |
| custom\_id          | string |         -        |
| name                | string |         -        |
| description         | string |      *empty*     |
| custom\_data        |  json  |      *empty*     |
| type                | string |     standard     |
| custom\_session\_id | string |      *empty*     |
| ordering            | string | larger-is-better |
| score\_preference   | string |   prefer-higher  |

{% hint style="info" %}
Click [here](https://docs.r4nkt.com/overview#common-properties) for information about common properties.
{% endhint %}

### Type

There are currently three types of leaderboards supported in r4nkt. A leaderboard's type can be found in its `type` property and can have one of the following values:

* `standard`: This type of leaderboard is one based on players' achievement points. Whenever an achievement is earned, then the points for all of their earned achievements are added together and recorded. This is done automatically and for each time span. No other customization is required.
* `session`: This type of leaderboard is nearly identical to the `standard` type.  The difference is that it only reflects achievement points that have been earned within the context of a session.
* `custom`: A custom leaderboard is one where the players' scores must be uploaded directly. When a player's score is submitted for a custom leaderboard, then it will be compared to the player's old score on that leaderboard, if it exists. If none exist, then the new one will be recorded. If the new one is better than the old one, then the new one will be added and the old one will be forgotten. This is done for each time span. Again, no other customization is required.

{% hint style="info" %}
For any given game, no more than one `standard` leaderboard is allowed.
{% endhint %}

{% hint style="info" %}
You cannot submit scores to`standard` or `session` leaderboards.
{% endhint %}

{% hint style="info" %}
When comparing scores the leaderboard's `ordering` property is used to determine which score is better **and** how to rank. Read more [here](#ordering).
{% endhint %}

{% hint style="warning" %}
Please note that, once created, a leaderboard's `type` property cannot be changed.
{% endhint %}

### Custom Session ID

For session-based leaderboards (`type` is set to `session`), a custom session ID is required.  This ID is used when reporting activity if the activity took place within some sort of custom session.  Whenever activity is reported when a custom session ID is provided, then those activities will be processed within such a context first.

{% hint style="warning" %}
Please note that, once created, a leaderboard's `custom_session_id` property cannot be changed.
{% endhint %}

### Ordering

A leaderboard's `ordering` property determines how the scores are interpreted as well as how rankings are determined.  It can have one of the following values:

* `larger-is-better`: These leaderboards consider larger scores as better than lower ones.
* `smaller-is-better`: These leaderboards consider smaller scores as better than larger ones.

### Score Preference

A leaderboard's `score_preference` property determines how new scores are compared to old scores when updating a given leaderboard. This applies to all leaderboard types and is applying the same regardless of the leaderboard's `ordering` property.

A leaderboard's `score_preference` can be set to one of the following values:

* `prefer-higher`: When comparing a new score to an old one, the new one will be added if it's greater than the old one.
* `prefer-lower`: When comparing a new score to an old one, the new one will be added if it's less than the old one.
* `prefer-first`: The first score will be added. All subsequent scores will be ignored.
* `prefer-last`: Each score that is submitted will added. Any previous scores will be removed.

## Rankings

Of course, a leaderboard is somewhat boring without the ability to see how the players are ranked.

### Leaderboard Rankings

Leaderboard rankings can be requested for any leaderboard.  Pagination is supported and rankings can be requested for any given time span, which defaults to `all-time`.

### Player Rankings

An individual player's ranking for a specified leaderboard is also available.  It can be requested for any given time span, but it defaults to `all-time`.