Leaderboard System

A leaderboard system tracks and ranks user performance based on scores earned through gameplay or other activities, like referrals.

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

How to set up a leaderboard system in the game?

• Fill out the form 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 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 to get the leaderboard data (1)

• Update your referral leaderboard variable with data from the Get Referral Leaderboard expression (2)

How to get the map-based leaderboard?

• Use the Request Best Scores Leaderboard action to get the leaderboard data (1)

• Update your map leaderboard variable with data from the Get Best Scores Leaderboard expression (2)

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.

{
  "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.

{
  "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.

{
  "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