# Leaderboard System

It typically includes modules for recording individual achievements, aggregating total scores, and handling point adjustments such as in-game spending. Referral-based leaderboards reward users for bringing new players by adding bonus points based on the referred user's performance. These systems provide an engaging way for players to track progress, compete, and earn rewards across multiple dimensions of the game.

[More info about the whole leaderboard system](https://docs.metaproprotocol.com/metapro-market/leaderboard)

## How to set up a leaderboard system in the game?

* [ ] [**Fill out the form**](https://docs.metaproprotocol.com/developer-documentation/plugin-configuration#https-forms.clickup.com-26441698-f-t6xz2-11152-384ali6tos1jco0h89) and choose whether you want to use the leaderboard system
* [ ] Set the value in the plugin

## How to get the general game leaderboard?

* [ ] Use the [**Request Leaderboard action**](#general-leaderboard) to get the leaderboard data
* [ ] Update your general leaderboard variable with data from the **Get Leaderboard** expression

## How to get the referral leaderboard?

* [ ] Use the [**Request Referral Leaderboard action**](#leaderboard-for-referral-bonuses) to get the leaderboard data (1)
* [ ] Update your referral leaderboard variable with data from the **Get Referral Leaderboard** expression (2)

<figure><img src="https://2351247042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9QQIPimQeOGE3C1HbWxf%2Fuploads%2FF0hTHeFi79XzqMQFbUAT%2Fimage.png?alt=media&#x26;token=5b41f1c7-328a-4257-88a1-aa3dd95ec406" alt=""><figcaption></figcaption></figure>

## How to get the map-based leaderboard?

* [ ] Use the [**Request Best Scores Leaderboard action**](#leaderboard-for-a-specific-map-best-scores) to get the leaderboard data (1)&#x20;
* [ ] Update your map leaderboard variable with data from the **Get Best Scores Leaderboard** expression (2)

<figure><img src="https://2351247042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9QQIPimQeOGE3C1HbWxf%2Fuploads%2F6XNFEEhi9d80w7rqSeuS%2Fimage.png?alt=media&#x26;token=e8f4e746-b6a9-45a1-b2d7-915e544b5992" alt=""><figcaption></figcaption></figure>

## Leaderboard Types

The plugin supports three types of leaderboards:

1. **General Leaderboard:** Tracks user performance.
2. **Leaderboard for a specific map** (best score leaderboard)
3. **Referral Leaderboard:** Tracks user referral activities.

## General Leaderboard

The **Request Leaderboard** action retrieves the leaderboard data based on the user's current score ranking, sorted in descending order. The action accepts three parameters: a limit on the number of leaderboard entries to retrieve (default is 20), a minimum balance, and a maximum balance. If the request is successful, the leaderboard data is processed to include additional user information such as username and avatar, retrieved from the user's profile.

The leaderboard is returned in the following structure:

* **results:** An array of leaderboard entries, where each object contains information about a user, such as their user ID, position, current score, total score, username, and avatar.
* **count:** Represents the total number of entries in the leaderboard.
* **personal:** An object with personal score data. Added if it exists.

Return data:

Once the leaderboard data is successfully retrieved and processed, it triggers the **On Leaderboard Received** condition and updates the leaderboard variable, which can be accessed using the **Get Leaderboard** expression. The expression returns a stringified array of the leaderboard objects within the `results` array, along with the total count of entries in the leaderboard.

```json
{
  "results": [
    {
      "userId": "user123",
      "position": 1,
      "currentScore": 3500,
      "totalScore": 5000,
      "username": "playerOne",
      "avatar": "https://example.com/avatar1.png"
    }, ...
  ],
  "count": 3,
  "personal": {
    "userId": "user456",
    "position": 2,
    "currentScore": 3200,
    "totalScore": 4800,
    "username": "playerTwo",
    "avatar": "https://example.com/avatar2.png"
  }
} // Example data
```

## Leaderboard for a specific map (best scores)

The **Request Best Scores Leaderboard** action retrieves the best scores for users on a specific map by interacting with the leaderboard API. This action accepts two parameters: Map ID to specify the map for which to retrieve the best scores and an optional limit to set the maximum number of entries (default is 20). It queries the leaderboard for user scores, sorts them by the best score achieved on the specified map, and enhances the leaderboard entries with user data such as username and avatar.

Upon successful execution, the action processes the response, combining the best score data with additional user profile information (e.g., username and avatar). The response structure is as follows:

* **results:** An array of leaderboard entries, each containing information about a user, including their user ID, position, best score on the map, username, and avatar.
* **count:** Represents the total number of entries in the leaderboard for the specified map.
* **personal:** An object with personal score data. Added if it exists.

Once the data is retrieved, it triggers the **On Best Scores Leaderboard Received** condition and updates the leaderboard data, which can be accessed using the **Get Best Scores Leaderboard** expression. The expression returns a stringified array of objects containing the leaderboard entries.

```json
{
  "results": [
    {
      "userId": "user123",
      "position": 1,
      "bestScore": 5000,
      "username": "playerOne",
      "avatar": "https://example.com/avatar1.png"
    }, ...
  ],
  "count": 3,
  "personal": {
    "userId": "user456",
    "position": 2,
    "bestScore": 4800,
    "username": "playerTwo",
    "avatar": "https://example.com/avatar2.png"
  }
} // Example data
```

## Leaderboard for referral bonuses

The Request **Referral Leaderboard** action retrieves a leaderboard containing users' referral scores, which represent bonuses accumulated from their downlines. This action requires several parameters:

* **Referral Leaderboard ID:** The ID of the referral leaderboard to query.
* **Referral Leaderboard API Key:** The API key required to access the referral leaderboard.
* **Limit (optional):** Specifies the maximum number of leaderboard entries to retrieve (default is 20).
* **Min Balance (optional):** The minimum balance filter for users' scores.
* **Max Balance (optional):** The maximum balance filter for users' scores.

The action sends a request to the leaderboard API, which returns a list of users and their referral-based scores. It enhances the leaderboard by fetching additional profile details (e.g., username and avatar) for each user. The leaderboard is returned in the following structure:

* **results:** An array of leaderboard entries, where each object contains information about a user, such as their user ID, position, current score, total score, username, and avatar.
* **count:** Represents the total number of entries in the leaderboard.
* **personal:** An object with personal score data. Added if it exists.

After successfully retrieving the referral leaderboard, it triggers the **On Referral Leaderboard Received** condition. The leaderboard data can be accessed using the **Get Referral Leaderboard** expression, which returns a stringified array of objects containing the leaderboard details.

```json
{
  "results": [
    {
      "userId": "user123",
      "position": 1,
      "currentScore": 3500,
      "totalScore": 5000,
      "username": "playerOne",
      "avatar": "https://example.com/avatar1.png"
    }, ...
  ],
  "count": 3,
  "personal": {
    "userId": "user456",
    "position": 2,
    "currentScore": 3200,
    "totalScore": 4800,
    "username": "playerTwo",
    "avatar": "https://example.com/avatar2.png"
  }
} // Example data
```