Skip to main content

Leaderboards

Last updated on

Overview

AccelByte Foundations’ Leaderboard service enables you to keep track of players’ scores and ranking in your game by collecting data from the Foundations' Statistics service, such as the number of matches played, a player’s matchmaking rating, and their experience points. The Foundations Leaderboard service then uses this data to calculate each player’s rank. AccelByte Foundations supports multiple leaderboards in one game, including a daily leaderboard for day-to-day player activities, a weekly leaderboard for weekly player recaps, a monthly leaderboard to record player activities each month, a seasonal leaderboard for seasonal player activities such as holiday events, and an all-time leaderboard to record player activities across the life of your game. Each type of leaderboard is explained in detail below.

Leaderboard Cycles

  • The Daily Leaderboard collect players' daily scores and ranking once the leaderboard has been created. When the leaderboard has been generated, players can start playing the game and the leaderboard service will collect their score and ranking until the daily reset time. Players have to keep playing to maintain their position on the daily leaderboard.
  • The Weekly Leaderboard are similar to the Daily Leaderboard, but player scores and rankings will be updated every week. Players have to keep playing to maintain their position on the weekly leaderboard. The Monthly Leaderboard is also similar to the Daily and Weekly Leaderboards. The player's score and ranking will be updated every month.
  • The All-Time Leaderboard do not have any time constraints; they will record the player’s score and ranking as long as the leaderboard exists in-game. As player scores continue to accumulate this leaderboard will be updated.
  • The Season Leaderboard run for a specific period of time that is set when the leaderboard is created. For example, if an event is running on the 1st of May between 00:30 AM and 2:30 AM, the season leaderboard will only record the rank and score of players who took part in that particular event. Once the event is over, the leaderboard will be reset.

How It Works

Single Leaderboard

Create a Leaderboard

The leaderboard will start tracking statistics from the beginning of its defined start time. At that time, the leaderboard will retrieve the player’s current statistic scores, which will become the initial scores for the all-time leaderboard. If the leaderboard data also includes a daily, weekly, monthly, or seasonal suffix, it will also map this to the statistic code.

leaderboard

Update a Player’s Statistic

The leaderboard consumes statistics events to collect players’ latest scores. Then, players' delta scores are added to the existing scores in the related daily, weekly, monthly, or seasonal leaderboards, and the all-time leaderboard score is updated with the latest score.

leaderboard

Reset a Leaderboard

Leaderboards can be reset manually or based on a predetermined reset time calculated when the leaderboard starts or is restarted.

leaderboard

Character Leaderboards

Update a Character Leaderboard

When a player levels up or enters a new arena, the game client sends their score data to the Statistics service. The character event is then published with additional data such as the character’s name and skills. The Leaderboard service then retrieves character score data from Kafka and saves the new score and rank data in its internal database.

leaderboard

Retrieve a Character Leaderboard

The game client retrieves leaderboard data from the Leaderboard service. Once called, the Leaderboard services will return all related leaderboard data, including additional information such as character names and skills.

leaderboard

Managing Leaderboards in the Admin Portal

Prerequisites

You need to have created a statistics configuration in the same game title before proceding. Statistic configurations are used to update player leaderboard rankings.

Create a New Leaderboard Configuration

  1. In the desired game title, expand Game Management and select Leaderboards.

  2. In the Leaderboard panel, click Create Leaderboard.

    Leaderboard

  3. The Add Leaderboard form will appear. Fill in the required fields.

    Leaderboard

    • Leaderboard Code: Input the Leaderboard Code with the same format as the StatCode input validation.
    • StatCode: Input the relevant StatCode that you configured in the Statistics service.
    • Name: Input the leaderboard name to be displayed to your players.
    • Start Date: Type the start date in RFC3339 standard format, e.g., 2020-10-02T15:00:00.05Z.
    • Daily: Input the Daily reset time for a daily leaderboard.
    • Weekly: Input a day and time for the Weekly reset time for a weekly leaderboard.
    • Monthly: Input a day and time for the Monthly reset time for a monthly leaderboard. For example, if you input the 1st in the Date field and 12:00 AM in the Time field, the reset time will be the first day of the month at 12:00AM.
    • Seasonal: If selected, you must input the number of days it will take for the leaderboard to reset in the Season Period Days field. The value must be greater than 31.
    • Order: Choose whether you want the players’ ranks to appear in Ascending or Descending order.
    • Icon: Select an Icon for your leaderboard config.
  4. Once completed, click Add to create your new leaderboard.

Retrieve Leaderboard Rankings

  1. Choose the leaderboard you want to see ranking data for by clicking on the corresponding Action column and selecting View.

    leaderboard

  2. In this example, we choose to see the all-time leaderboard rankings. You can view the rankings for all types of leaderboards.

    leaderboard

Delete or Archive a Leaderboard

  1. Choose the leaderboard you want to delete by clicking the More Options (...) button in the Actions column and selecting Delete.

  2. The Delete Leaderboard form will appear. Select the Take a snapshot before deletion checkbox if you want to archive the first 1,000 records of the leaderboard.

    leaderboard

  3. Type DELETE in the textbox and click the Delete button to confirm. Your leaderboard will be deleted.

View Archived Leaderboard Data

  1. In the Game Management section, open the Leaderboard page and click the Snapshots tab.

  2. In the Snapshot tab, you can see all of the archived leaderboards. To open a leaderboard, click View in the leaderboard’s Action menu.

  3. If you have any archived data, they will appear here.

    leaderboard

Implementing Leaderboards using the CLient SDKs

Retrieve all Player Rankings

Use the following function to retrieve all player rankings using a specific leaderboard code. The data will be presented in descending order.

FString LeaderboardCode = FString("SomeLeaderboardCode");
EAccelByteLeaderboardTimeFrame TimeFrame = EAccelByteLeaderboardTimeFrame::ALL_TIME;
int32 Offset = 0;
int32 Limit = 99;

FRegistry::Leaderboard.GetRankings(LeaderboardCode, TimeFrame, Offset, Limit, THandler<FAccelByteModelsLeaderboardRankingResult>::CreateLambda([](const FAccelByteModelsLeaderboardRankingResult& Result)
{
// Do something if GetRankings has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetRankings has an error
UE_LOG(LogTemp, Log, TEXT("Error GetRankings, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Retrieve a Player Ranking

Use the following code to retrieve a specific player’s ranking using their User ID and the desired leaderboard code.


FString UserId = FString("SomeUserId");
FString LeaderboardCode = FString("SomeLeaderboardCode");

FRegistry::Leaderboard.GetUserRanking(UserId, LeaderboardCode, THandler<FAccelByteModelsUserRankingData>::CreateLambda([](const FAccelByteModelsUserRankingData& Result)
{
// Do something if GetUserRanking has been successful
}), FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
// Do something if GetUserRanking has an error
UE_LOG(LogTemp, Log, TEXT("Error GetUserRanking, Error Code: %d Error Meessage: %s"), ErrorCode, *ErrorMessage);
}));