Leaderboards

Leaderboards

Epic Online Services Interface: Leaderboards Interface

The Leaderboards Interface gives developers using Epic Online Services (EOS) the ability to rank scores from their entire player base, so that players can compete with their friends or other players worldwide for the top score. Each game can support multiple leaderboards, collecting scores from different sources, and ranking them with different scoring modes.

Functions

These functions are provided for handling leaderboards:

• EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex
• EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId
• EpicGames_Leaderboards_CopyLeaderboardRecordByIndex
• EpicGames_Leaderboards_CopyLeaderboardRecordByUserId
• EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex
• EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId
• EpicGames_Leaderboards_GetLeaderboardDefinitionCount
• EpicGames_Leaderboards_GetLeaderboardRecordCount
• EpicGames_Leaderboards_GetLeaderboardUserScoreCount
• EpicGames_Leaderboards_QueryLeaderboardDefinitions
• EpicGames_Leaderboards_QueryLeaderboardRanks
• EpicGames_Leaderboards_QueryLeaderboardUserScores

Constants

These are the constants used for leaderboards:

• EpicGames_LeaderboardAggregation

Structs

These are the structures used by this API:

• LeaderboardDefinition
• LeaderboardRecord
• LeaderboardUserScore

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardDefinitionByIndex

This function fetches a leaderboard definition from the cache using an index.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardDefinitions to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex(index)

Argument	Type	Description
index	Real	Index of the leaderboard definition to retrieve from the cache

Returns:

LeaderboardDefinition

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardDefinitionCount();
for(var i = 0 ; i < _count ; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex(i);
    var _LeaderboardId = _struct.LeaderboardId;
}

The above code shows an example of how the function should be used. The leaderboard definition data is returned providing an leaderboard index.

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId

This function fetches a leaderboard definition from the cache using a leaderboard ID.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardDefinitions to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId(leaderboardID)

Argument	Type	Description
leaderboardID	String	The ID of the leaderboard whose definition you want to copy from the cache

Returns:

LeaderboardDefinition

Example:

var _struct = EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId("MyLeaderboard");
if(_struct.status == EpicGames_Success)
{
    var LeaderboardId = _struct.LeaderboardId;
}

The above code shows an example of how the function should be used. The leaderboard definition data is returned providing a leaderboard ID.

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardRecordByIndex

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardRecordByIndex

This function fetches a leaderboard record from a given index.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardRanks to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardRecordByIndex(index)

Argument	Type	Description
index	Real	Index of the leaderboard record to retrieve from the cache

Returns:

LeaderboardRecord

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardRecordCount();
for(var i = 0 ; i < _count ; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardRecordByIndex(i);
    var _rank = struct.Rank;
}

The above code shows an example of how the function should be used. The leaderboard record data is returned providing a leaderboard index.

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardRecordByUserId

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardRecordByUserId

This function fetches a leaderboard record from a given user ID.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardRanks to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardRecordByUserId(userId)

Argument	Type	Description
userId	String	Leaderboard data will be copied from the cache if it relates to the user matching this Product User ID

Returns:

LeaderboardRecord

Example:

var _struct = EpicGames_Leaderboards_CopyLeaderboardRecordByUserId("MyLeaderboard");
if(_struct.status == EpicGames_Success)
{
    var _rank = struct.Rank;
}

The above code shows an example of how the function should be used. The leaderboard record data is returned providing an user ID.

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardUserScoreByIndex

This function fetches a leaderboard user score from a given index.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardUserScores to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex(index, statName)

Argument	Type	Description
index	Real	The index of the sorted leaderboard user score to retrieve from the cache.
statName	String	The name of the stat used to rank the leaderboard.

Returns:

LeaderboardUserScore

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardUserScoreCount();
for(var i = 0 ; i < _count ; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex(i);
    var _score = _struct.Score;
}

The above code shows an example of how the function should be used. The leaderboard user score is returned providing an index.

---

Back To Top

EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId

Epic Online Services Function: EOS_Leaderboards_CopyLeaderboardUserScoreByUserId

This function fetches leaderboard user score from a given user ID.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardUserScores to store values in cache.

Syntax:

EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId(userId, statName)

Argument	Type	Description
userId	String	The Product User ID to look for when copying leaderboard score data from the cache
statName	String	The name of the stat that is used to rank this leaderboard

Returns:

LeaderboardUserScore

Example:

var _struct = EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId("MyLeaderboard");
if(_struct.status == EpicGames_Success)
{
    var _score = struct.Score;
}

The above code shows an example of how the function should be used. The leaderboard user score is returned providing an user ID.

---

Back To Top

EpicGames_Leaderboards_GetLeaderboardDefinitionCount

Epic Online Services Function: EOS_Leaderboards_GetLeaderboardDefinitionCount

This function fetch thees number of leaderboards definitions that are cached locally.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardDefinitions to store values in cache.

Syntax:

EpicGames_Leaderboards_GetLeaderboardDefinitionCount()

Returns:

Real

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardDefinitionCount();
for(var i = 0 ; i < _count ; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex(i);
    var _leaderboardId = _struct.LeaderboardId;
}

The above code shows an example of how the function should be used. After a successful call to EpicGames_Leaderboards_QueryLeaderboardDefinitions, the function EpicGames_Leaderboards_GetLeaderboardDefinitionCount will return the number of entries in the query array which can then be accessed using the EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex function.

---

Back To Top

EpicGames_Leaderboards_GetLeaderboardRecordCount

Epic Online Services Function: EOS_Leaderboards_GetLeaderboardRecordCount

This function fetches the number of leaderboard records that are cached locally.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardRanks to store values in cache.

Syntax:

EpicGames_Leaderboards_GetLeaderboardRecordCount()

Returns:

Real

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardRecordCount();
for(var i = 0 ; i < _count ; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardRecordByIndex(i);
    var _rank = _struct.Rank;
}

The above code shows an example of how the function should be used. After a successful call to EpicGames_Leaderboards_QueryLeaderboardRanks, the function EpicGames_Leaderboards_GetLeaderboardRecordCount will return the number of entries in the query array which can then be accessed using the EpicGames_Leaderboards_CopyLeaderboardRecordByIndex function.

---

Back To Top

EpicGames_Leaderboards_GetLeaderboardUserScoreCount

Epic Online Services Function: EOS_Leaderboards_GetLeaderboardUserScoreCount

This function fetches the number of leaderboard user scores that are cached locally.

Note

Requires a previous call to EpicGames_Leaderboards_QueryLeaderboardUserScores to store values in cache.

Syntax:

EpicGames_Leaderboards_GetLeaderboardUserScoreCount()

Returns:

Real

Example:

var _count = EpicGames_Leaderboards_GetLeaderboardUserScoreCount();
for(var i = 0 ; i < _count; i++)
{
    var _struct = EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex(i);
    var _score = _struct.Score;
}

The above code shows an example of how the function should be used. After a successful call to EpicGames_Leaderboards_QueryLeaderboardUserScores, the function EpicGames_Leaderboards_GetLeaderboardUserScoreCount will return the number of entries in the query array which can then be accessed using the EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex function.

---

Back To Top

EpicGames_Leaderboards_QueryLeaderboardDefinitions

Epic Online Services Function: EOS_Leaderboards_QueryLeaderboardDefinitions

This function queries for a list of existing leaderboards definitions including their attributes. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

• EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex
• EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId
• EpicGames_Leaderboards_GetLeaderboardDefinitionCount

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

EpicGames_Leaderboards_QueryLeaderboardDefinitions(userID, startTime, endTime)

Argument	Type	Description
userID	String	Product User ID for user who is querying definitions. Must be set when using a client policy that requires a valid logged in user. Not used for Dedicated Server where no user is available.
startTime	Int64	An optional POSIX timestamp for the leaderboard's start time, or undefined.
endTime	Int64	An optional POSIX timestamp for the leaderboard's end time, or undefined.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	"EpicGames_Leaderboards_QueryLeaderboardDefinitions"
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
identifier	Real	The asynchronous listener ID

Example:

identifier = EpicGames_Leaderboards_QueryLeaderboardDefinitions();

The code sample above save the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Leaderboards_QueryLeaderboardDefinitions")
if(async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

---

Back To Top

EpicGames_Leaderboards_QueryLeaderboardRanks

Epic Online Services Function: EOS_Leaderboards_QueryLeaderboardRanks

This function retrieves top leaderboard records by rank in the leaderboard matching the given leaderboard ID. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

• EpicGames_Leaderboards_CopyLeaderboardRecordByIndex
• EpicGames_Leaderboards_CopyLeaderboardRecordByUserId
• EpicGames_Leaderboards_GetLeaderboardRecordCount

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

EpicGames_Leaderboards_QueryLeaderboardRanks(userID, LeaderboardId)

Argument	Type	Description
userID	String	The ID of the leaderboard whose information you want to retrieve
LeaderboardId	String	Product User ID for user who is querying ranks. Must be set when using a client policy that requires a valid logged in user. Not used for Dedicated Server where no user is available

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	"EpicGames_Leaderboards_QueryLeaderboardRanks"
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
identifier	Real	The asynchronous listener ID

Example:

identifier = EpicGames_Leaderboards_QueryLeaderboardRanks(userID, LeaderboardId);

The code sample above save the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Leaderboards_QueryLeaderboardRanks")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

---

Back To Top

EpicGames_Leaderboards_QueryLeaderboardUserScores

Epic Online Services Function: EOS_Leaderboards_QueryLeaderboardUserScores

This function queries for a list of scores for a given list of users. Once the callback has been fired with a successful EpicGames_Result, it is possible to call one of the following functions:

• EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex
• EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId
• EpicGames_Leaderboards_GetLeaderboardUserScoreCount

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

EpicGames_Leaderboards_QueryLeaderboardUserScores(userID, LeaderboardId, name, aggregation, startTime, endTime)

Argument	Type	Description
userID	String	The argument to be passed in
LeaderboardId	String	Product User ID indicating the users whose scores you want to retrieve
name	String	The name of the stat to query.
aggregation	EpicGames_LeaderboardAggregation	Aggregation used to sort the cached user scores.
startTime	Real	An optional POSIX timestamp, or undefined; results will only include scores made after this time
endTime	Real	An optional POSIX timestamp, or undefined; results will only include scores made before this time

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	"EpicGames_Leaderboards_QueryLeaderboardUserScores"
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
identifier	Real	The asynchronous listener ID

Example:

identifier = EpicGames_Leaderboards_QueryLeaderboardUserScores(userID, LeaderboardId, name, aggregation, startTime, endTime);

The code sample above save the identifier that can be used inside a Social Async Event.

if (async_load[? "type"] == "EpicGames_Leaderboards_QueryLeaderboardUserScores")
if (async_load[? "identifier"] == identifier)
{
    if (async_load[? "status"] == EpicGames_Success)
    {
        show_debug_message(async_load[? "type"] + " succeeded!");
    }
    else
    {
         show_debug_message(async_load[? "type"] + " failed: " + async_load[? "status_message"]);
    }
}

The code above matches the response against the correct event type and logs the success of the task.

---

Back To Top

EpicGames_LeaderboardAggregation

Epic Online Services Enum: EOS_ELeaderboardAggregation

These constants represent the different leaderboard aggregation types.

These constants are referenced by the following functions:

• EpicGames_Leaderboards_QueryLeaderboardUserScores

These constants are referenced by the following structs:

• LeaderboardDefinition

Member	Description
EpicGames_LA_Min	Scores are aggregated by minimum.
EpicGames_LA_Max	Scores are aggregated by maximum.
EpicGames_LA_Sum	Scores are aggregated by the sum of the values.
EpicGames_LA_Latest	Scores are aggregated by the last value.

---

Back To Top

LeaderboardUserScore

A leaderboard definition is represented by a struct and contains information about a single leaderboard user score.

This struct is referenced by the following functions:

• EpicGames_Leaderboards_CopyLeaderboardUserScoreByIndex
• EpicGames_Leaderboards_CopyLeaderboardUserScoreByUserId

Member	Type	Description
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
UserId	String	The Product User ID of the user who got this score
Score	Real	Leaderboard score

---

Back To Top

LeaderboardRecord

A leaderboard record is represented by a struct and contains information about a single leaderboard record.

This struct is referenced by the following functions:

• EpicGames_Leaderboards_CopyLeaderboardRecordByIndex
• EpicGames_Leaderboards_CopyLeaderboardRecordByUserId

Member	Type	Description
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
UserId	String	The Product User ID associated with this record
Rank	Real	Sorted position on leaderboard
Score	Real	Leaderboard score
UserDisplayName	String	The latest display name seen for the user since they last time logged in. This is empty if the user does not have a display name set

---

Back To Top

LeaderboardDefinition

An leaderboard definition is represented by a struct and contains information about a single leaderboard definition.

This struct is referenced by the following functions:

• EpicGames_Leaderboards_CopyLeaderboardDefinitionByIndex
• EpicGames_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId

Member	Type	Description
status	EpicGames_Result	The status code for the operation. EpicGames_Success indicates that the operation succeeded; other codes indicate errors
status_message	String	Text representation of the status code
LeaderboardId	String	Unique ID to identify leaderboard.
StatName	String	Name of stat used to rank leaderboard.
StartTime	Real	The POSIX timestamp for the start time, or EpicGames_LEADERBOARDS_TIME_UNDEFINED.
EndTime	Real	The POSIX timestamp for the end time, or EpicGames_LEADERBOARDS_TIME_UNDEFINED.
Aggregation	EpicGames_LeaderboardAggregation	used to sort the leaderboard.