Leaderboards Interface

A leaderboard is a list of players ranked by an in-game statistic. Leaderboards encourage competition between players, their friends, and the rest of the world, for the top score in your game. Games can feature multiple modes that award scores. Each of these modes can have its own leaderboard or leaderboards.

Leaderboards can rank entries in the following ways:

• Ascending: Lower scores are ranked better than higher scores.

  • The Fortnite wins leaderboard is organized in descending order since more wins is desirable.

• Descending: Higher scores are ranked better than lower scores.

  • Lap time leaderboards in racing games are organized in ascending order since faster lap times are more desirable.

The Online Services Leaderboards Interface provides developers with tools to display and update leaderboards from within their games. Leaderboard data can be very large since each leaderboard your game supports could have an entry for every user account that has played your game. For this reason, the leaderboards interface retrieves data in chunks. Games that implement the leaderboards interface can request chunks of the leaderboard in different ways as described below in the Functions section and, in more detail, in the Read Leaderboard Entries section.

API Overview

Functions

The following table provides a high-level overview of the functions provided by the leaderboards interface:

Primary Struct

The leaderboards interface's functionality is primarily communicated through the FLeaderboardEntry struct:

Configuration

To update a leaderboard score using stats, you must configure the leaderboards interface in the engine configuration files, such as DefaultEngine.ini. The leaderboards interface works in conjunction with the Stats Interface to track stats for leaderboard rankings.

General Syntax

[OnlineServices.Leaderboards]
bIsTitleManaged=true
!LeaderboardDefinitions=ClearDefinitions
+LeaderboardDefinitions=(Name=<StatName0>, Id=<Id0>, UpdateMethod=[KeepBest | Force], OrderMethod=[Ascending | Descending])
+LeaderboardDefinitions=(Name=<StatName1>, Id=<Id1>, UpdateMethod=[KeepBest | Force], OrderMethod=[Ascending | Descending])
...

The following Leaderboard Definition table explains the syntax for adding a leaderboard definition to an engine configuration file.

Leaderboard Definition

Configuration Example

Suppose that you have a simple game with a single leaderboard titled "Total Game Points" tracked by a statistic of the same name configured with the stats interface:

[OnlineServices.Stats]
!StatDefinitions=ClearDefinitions
+StatDefinitions=(Name=Total_Game_Points, Id=0, ModifyMethod=Sum)

[OnlineServices.Leaderboards]
bIsTitleManaged=true
!LeaderboardDefinitions=ClearDefinitions
+LeaderboardDefinitions=(Name=Total_Game_Points, Id=0, UpdateMethod=KeepBest, OrderMethod=Descending)

In this configuration, the leaderboard:

• keeps the best score for the Total_Game_Points statistic for each player, and

• is organized in descending order, since higher point totals are more desirable.

Read Leaderboard Entries

There are three different ways to read leaderboard entries with the leaderboards interface. Leaderboard entries can be read in the following ways:

• For specific users

• Around a particular rank

• Around a given user

Below we show a visual representation of what each of these methods retrieves with the "Total Game Points" leaderboard configured in the configuration example above.

For Specific Users

Use the ReadEntriesForUsers function to retrieve leaderboard entries for specific users. This function takes in a list of user IDs for the individual users whose rank you wish to query.

Example

Suppose that you have the leaderboard below titled "Total Game Points" and call ReadEntriesForUsers with the following parameters:

UE::Online::FReadEntriesForUsers::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.AccountIds = {"9P8H4GQ-HNO5GA4", "3CN9H8E-VNO3G3C", "OHB8RA2-OHSEBSE"};
Params.BoardName = TEXT("Total Game Points");

If the call returns successfully, you can access the columns marked as retrieved in the returned TOnlineResult:

Around a Particular Rank

Use the ReadEntriesAroundRank function to retrieve leaderboard entries around a particular leaderboard rank. This function takes in:

• a rank at which you want to start reading leaderboard entries, and

• a limit for the number of entries to read.

Example

Suppose that you have the leaderboard below titled Total Game Points and call ReadEntriesAroundRank with the following parameters:

UE::Online::FReadEntriesAroundRank::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.Rank = 2;
Params.Limit = 2;
Params.BoardName = TEXT("Total Game Points");

If the call returns successfully, you can access the columns marked as retrieved in the returned TOnlineResult:

Around a Given User

Use the ReadEntriesAroundUser function to retrieve leaderboard entries around a particular user. This function takes in:

• the user around which you want to read entries,

• an offset to indicate where to start reading entries, and

• a limit for the total number of entries to read.

Example

Suppose that you have the leaderboard below titled Total Game Points and call ReadEntriesAroundUser with the following parameters:

UE::Online::FReadEntriesAroundUser::Params Params;
Params.LocalAccountId = "LLV54WB-3C678QQ";
Params.Offset = -1;
Params.Limit = 3;
Params.BoardName = TEXT("Total Game Points");

If the call returns successfully, you can access the columns marked as retrieved in the returned TOnlineResult:

More Information

Header File

Consult the Leaderboards.h header file directly for more information as needed. The Leaderboards Interface header file Leaderboards.h is located in the directory:

UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

For instructions on how to obtain the UE source code, see our documentation on Downloading Unreal Engine Source Code.

Function Parameters and Return Types

See the Functions section of the Online Services Overview page for an explanation of function parameters and return types, including how to pass parameters and processing the results when functions return.