# Leaderboards

There are three primary APIs to be aware of:

* Rank
* Score
* Leaderboard

{% hint style="warning" %}
Before working with the Rank and Score APIs, you must first create a new Leaderboard.
{% endhint %}

### Leaderboard Properties

Leaderboards have the following properties:

* **id**: The database id of this leaderboard. This is assigned automatically when it is added to the DB.
* **Name**: The name of the leaderboard as a string. This must be unique across all leaderboards.
* **TimeStrategyType**: The time strategy for the leaderboard. Current options are `ALL_TIME` and `EPOCHAL`. `EPOCHAL` leaderboards allow for recurring leaderboards that are intended to repeatedly reset after a certain time interval (defined by **EpochInverval**). 
* **ScoreStrategyType**: The score strategy for the leaderboard. Current options are `OVERWRITE_IF_GREATER` and `ACCUMULATE`.
* **Title**: The user-presentable name or title for for the leaderboard as a string. 
* **ScoreUnits**: The units-of measure for the score type of the leaderboard as a string. This can be anything you want, such as points, crackers, ducats - you name it! 
* **FirstEpochTimestamp**: The time at which the leaderboard epoch intervals should begin (in ms). If null, then the leaderboard is all-time and not epochal. [If this value is provided during creation of the Leaderboard, then **epochInterval** must also be provided. ](#user-content-fn-1)[^1]
* **EpochInterval**: The duration for a leaderboard epoch interval (in ms). If null, then the leaderboard is all-time and not epochal. If this value is provided during creation of the Leaderboard, then **firstEpochTimestamp** must also be provided.

Once you have your Leaderboard defined, use the `CreateLeaderboard` function in the **LeaderboardApi** to create it in Elements.

You can also set up and manipulate your leaderboards on the server side from your lua code:

```lua
local namazu_leaderboard = require "namazu.elements.dao.leaderboard"
namazu_leaderboard.create_leaderboard(new_leaderboard)
```

Now that you have a Leaderboard created, you can use the **ScoreApi** and **RankApi** to interact with it. The **ScoreApi** gives you the following function, which creates or updates a score on the specified leaderboard for the Profile of the player making the request and returns the Score as it was written to the DB.

```
Score createOrUpdateScore(String leaderboardNameOrId, Score score);
```

You'll want to update the leaderboard score whenever someone does something that warrants posting to a Leaderboard, such as being awarded a score for a game. 

Depending on the **ScoreStrategyType** of the Leaderboard, this will either add to the entry (`ACCUMULATE`), or compare and overwrite it if it is greater than the previous entry (`OVERWRITE_IF_GREATER`).

The **RankApi** provides the following functions:

Given the leaderboard name or id, this function will return all Rank instances sorted in order: 

{% code overflow="wrap" %}

```
Pagination<Rank> getRanksForGlobal(String leaderboardNameOrId, int offset, int count, long leaderboardEpoch);
```

{% endcode %}

Given the leaderboard name or ID, this function will return all Rank instances sorted in order. This allows the the result set to be skipped forward to make the supplied Profile appear in the result set:&#x20;

{% code overflow="wrap" %}

```
Pagination<Rank> getRanksForGlobalRelative(String leaderboardNameOrId, String profileId, int count, long leaderboardEpoch);
```

{% endcode %}

Given the leaderboard name or id, this function will return all Rank instances for friends of the User sorted in order. This allows the the result set to be skipped forward to make the supplied Profile appear in the result set:&#x20;

{% code overflow="wrap" %}

```
Pagination<Rank> getRanksForFriends(String leaderboardNameOrId, Profile profileId, int offset, int count, long leaderboardEpoch);
```

{% endcode %}

Given the leaderboard name or id, this will return all Rank instances for friends of the user sorted in order. This allows the the result set to be skipped forward to make the Profile for the supplied profile id appear in the result set. Additionally this will filter the results to only include friends of the supplied Profile:&#x20;

{% code overflow="wrap" %}

```
Pagination<Rank> getRanksForFriendsRelative(String leaderboardNameOrId, Profile profileId, int offset, int count, long leaderboardEpoch);
```

{% endcode %}

[^1]: