Leaderboards

1. Overview

Nowadays, the leaderboard is almost an essential feature for online games. By displaying the Leaderboard and player ranking details, you can create a great competitive atmosphere for the players.

2. Key Concepts

First of all, the PGOS Leaderboard service uses the Statistics service as its data source. Before creating a leaderboard, you should create a Stat in the Statistics service to track the player or global-wide data. Once the data of the Stat is updated after creating the leaderboard, the ranking data in the leaderboard will be updated automatically.

tip

It's worth noting that the existing data in stat before creating the leaderboard will be not updated into the leaderboard.

The key features of the leaderboard are:

Persistent and cycled leaderboard
The ranking data in the persistent leaderboard will be not reset. By contrast, the ranking data in the cycled leaderboard will be reset periodically according to the stat cycle you chose for creating the leaderboard.
Enormous ranking data scale and real-time updating
The core engine of the PGOS leaderboard uses a SkipList similar algorithm to achieve high-performance real-time sorting while storing the data in memory and database dynamically to save cost as much as possible.
Multi-values sorting
There are several sorting factors, you can set their order type separately.
- Value: The value of the data item in the stat
- Secondary Value: The secondary value of the data item in the stat
- Updated Time: The time when the data item is updated
The priority of sorting factors is: Value > Secondary Value > Updated Time
For sorting result stability, the Key is another sort factor, which is in alphabetic order. It's a useful workaround. In this way, you can get a stable sorting result when the value, secondary value, and Updated Time are equal separately.
Archiving for cycled leaderboard
When the time frame of a cycled leaderboard is switched, all the ranking data will be reset. The ranking data of the previous time frame will be archived. You can access them by API or Portal.
Support retrieving ranking items with neighbor items
You can retrieve ranking items with neighbor items by API. Most games do it to display to the player where his ranking is and who's the neighboring players on the ranking.
Support retrieving any offset of the rank list
You can retrieve the ranking item in any offset accurately.
Support retrieving friends ranking list
You can retrieve the current friends ranking list of the specified leaderboard. The leaderboard's stat item key should be filled with player id.

3. Manage on Portal

3.1 Add New Leaderboard

Field description:

Name: The name of the new leaderboard. It can only contain letters, numbers, and underscores, and cannot start with a number.
Description (optional): The description of the leaderboard.
Bound Stat: Associate an existing stat as the data source of the leaderboard.
Order Config: Specifies how items in the leaderboard are sorted.
- Value: Sorting method of the item value. The rankings are sorted by item value first.
- Secondary Value: Sorting method of the secondary value. It is the second priority sorting rule when the item value is the same.
  If it doesn't matter, selecting "Not Order" can improve the performance of the backend.
- Update Time: Sorting method of the item update time. It is the third priority sorting rule when the item value and secondary value are the same.
  If it doesn't matter, selecting "Not Order" can improve the performance of the backend.

If everything is okay then you will get a new leaderboard:

3.2 Delete Leaderboard

If you want to remove a leaderboard, click the Delete link button in the leaderboard list:

❗ Note: Once a leaderboard is deleted, its data can no longer be accessed through the PgosSDK or HTTP API.

3.3 Manage Leaderboard Items

Click the leaderboard name to start managing leaderboard items:

After the leaderboard name clicking, you will see a leaderboard item list:

If you want to search for a specific item, input the item key and click the Search button:

If you want to search multiple items at the same time, enable the multi-keys checkbox, and input multiple item keys in the search box.

4. Access via SDK

4.1 For Game Client

The game can query leaderboard data on the game client through PgosSDK.

API	Description
GetRankingList	Query the current ranking list of the specified leaderboard.
GetRankingItemPos	Query the current ranking list item with neighbor items of the specified leaderboard.
GetFriendsRankingList	Query the current friends ranking list of the specified leaderboard. The leaderboard's stat item key should be filled with player id.

4.1.1 GetRankingList Client API

Interface prototype:

/**
* Query the current ranking list of the specified leaderboard.
*
* @param Params Request structure for querying the current ranking list.
*/
void GetRankingList(
    const FClientGetRankingListParams& Params,
    TFunction<void(const FPgosResult& Ret, const FClientLBRankingListResult* Data)> Callback) const;

struct FClientGetRankingListParams
{
  /** The name of the leaderboard to query. */
  FString leaderboard_name;
  /** The starting position of the query. */
  int32 offset = 0;
  /** The query count. */
  int32 count = 0;
};

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto Leaderboard = IPgosSDKCpp::Get().GetClientLeaderboardAPI();
 if (Leaderboard)
 {
     FClientGetRankingListParams Params;
     Params.leaderboard_name = TEXT("KillingRanking");
     Params.offset = 0;
     Params.count = 10;
     Leaderboard->GetRankingList(Params, [](const FPgosResult& Ret, const FClientLBRankingListResult* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetRankingList Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetRankingList Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

4.1.2 GetRankingItemPos Client API

Interface prototype:

/**
* Query the current ranking list item with neighbor items of the specified leaderboard.
*
* @param Params Request structure for querying the current ranking list item with neighbor items.
*/
void GetRankingItemPos(
    const FClientGetRankingItemPosParams& Params,
    TFunction<void(const FPgosResult& Ret, const FClientLBRankingItemPos* Data)> Callback) const;

struct FClientGetRankingItemPosParams
{
  /** The name of the leaderboard to query. */
  FString leaderboard_name;
  /** The stat item key to query. */
  FString key;
  /**
   * Specify the desired number of preceding and subsequent neighbors, ranging from 0 to 10.
   * For example: if neighbor_cnt is 3, then you will get 3 preceding neighbors and 3 subsequent neighbors.
   */
  int32 neighbor_cnt = 0;
};

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
 auto Leaderboard = IPgosSDKCpp::Get().GetClientLeaderboardAPI();
 if (Leaderboard)
 {
     FClientGetRankingItemPosParams Params;
     Params.leaderboard_name = TEXT("KillingRanking");
     Params.key = TEXT("p600001");
     Params.neighbor_cnt = 3;
     Leaderboard->GetRankingItemPos(Params, [](const FPgosResult& Ret, const FClientLBRankingItemPos* Data) {
         if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
         {
             UE_LOG(LogTemp, Log, TEXT("GetRankingItemPos Success"));
         }
         else
         {
             UE_LOG(LogTemp, Log, TEXT("GetRankingItemPos Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
         }
     });
 }
}

4.1.3 GetFriendsRankingList Client API

Query the current friends ranking list of the specified leaderboard. The leaderboard's stat item key should be filled with player id.

Interface prototype:

/**
* Query the current friends ranking list of the specified leaderboard. The leaderboard's stat item key should be filled with player id.
* 
* @param Params Request structure for querying the current friends ranking list.
*/
void GetFriendsRankingList(
      const FClientGetFriendsRankingListParams& Params,
      TFunction<void(const FPgosResult& Ret, const FClientLBFriendsRankingListResult* Data)> Callback) const;

struct FClientGetFriendsRankingListParams 
{
    /** The name of the leaderboard to query. */
    FString leaderboard_name;
};

/** Response for get friends ranking list. */
struct PGOSSDKCPP_API FClientLBFriendsRankingListResult 
{
    /** List of friends ranking items. The stat item key was filled with player id. */
    TArray<FClientLBRankingItem> items;
    /**
    * Friends' details. key: player id
    * Note that this only contains the player information of friends, not my own. The 'items' contains my ranking.
    */
    TMap<FString, FClientPlayerFriendInfo> friend_infos;
};

Example Code:

#include "PgosSDKCpp.h"

void SomeUObjectClass::SomeFunction()
{
   auto Leaderboard = IPgosSDKCpp::Get().GetClientLeaderboardAPI();
   if (Leaderboard)
   {
       FClientGetFriendsRankingListParams Params;
       Params.leaderboard_name = TEXT("KillingRanking");
       Leaderboard->GetFriendsRankingList(Params, [](const FPgosResult& Ret, const FClientLBFriendsRankingListResult* Data) {
           if (Ret.err_code == (int32)Pgos::PgosErrCode::kSuccess)
           {
               UE_LOG(LogTemp, Log, TEXT("GetFriendsRankingList Success"));
           }
           else
           {
               UE_LOG(LogTemp, Log, TEXT("GetFriendsRankingList Failed: err_code=%d, err_msg=%s"), Ret.err_code, *Ret.msg);
           }
       });
   }
}

4.2 Key Errors Handling

Error Code	Relevant API	Handling Suggestion
kBackendLeaderboardNotExist	GetRankingList Client API GetRankingItemPos Client API	Leaderboard does not exist. A new one needs to be created for use.
kBackendLBKeyNotExist	GetRankingItemPos Client API	The specified key to query does not exist in the leaderboard.

1. Overview​

2. Key Concepts​

3. Manage on Portal​

3.1 Add New Leaderboard​

3.2 Delete Leaderboard​

3.3 Manage Leaderboard Items​

4. Access via SDK​

4.1 For Game Client​

4.1.1 GetRankingList Client API​

4.1.2 GetRankingItemPos Client API​

4.1.3 GetFriendsRankingList Client API​

4.2 Key Errors Handling​