Leaderboards Interface

Interface to handle online leaderboards

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.

To access the Leaderboards Interface, acquire an EOS_HLeaderboards handle through the Platform Interface function, EOS_Platform_GetLeaderboardsInterface. All Leaderboards Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking in order for callbacks to trigger when operations complete.

The Leaderboard Interface sets up and manages leaderboards, but does not populate them with score data. Instead, leaderboards draw on data that the Stats Interface creates and maintains.

Creating Leaderboards

Before you can access a leaderboard in-game, you must use the Developer Portal to set up the stats that your leaderboard will track (see the Stats Interface for more information), and define the leaderboard itself. Defining the leaderboard involves specifying:

  • The stat (or score) that the leaderboard tracks

  • The method the leaderboard uses to rank players

  • The starting and ending time for the leaderboard's overall lifespan

Once you have set up your stats and leaderboards, you can access them through the EOS SDK.

Stats and Milestones

EOS Leaderboards are driven by our EOS Stats system. Each leaderboard uses a specific stat as the score that it tracks. See the Stats Interface for more information.

The EOS Leaderboards interface supports querying data for ranked, worldwide data and unranked friend data. Any stat in our system can be used as a friend, clan, or other group-based leaderboard and are viewed by simply querying individual players' stats. Global leaderboards, on the other hand, require specific configuration. For scalability reasons, we limit both the number of global leaderboards you can have and the number of actual entries for the leaderboard we track. We do not track the entire global leaderboard, we simply keep track of the top 1000 (+ 1000 overflow) scores. We keep an extra 1000 entries because a developer may choose to remove certain entries from the leaderboard (for cheating, smurfing, privacy opt-out, or any other reason) so we keep extra values to fill out the top 1000 after those are removed. While the decision to only track the top 1000 entries does mean the majority of players will not see themselves on the leaderboard, we believe this to be good as global leaderboards only provide value for the top players. Friends leaderboards and other small, closed groups provide a lot more interactivity and value for players, giving them goals they can reasonably accomplish with meaningful feedback.

Each leaderboard references a number of Stats milestones in order to bin Stat aggregations necessary to accurately compute leaderboard state. The number of leaderboards a single user can have is a function of how many Stats milestones a given user account is allowed to contain. The following table describes this function per leaderboard type (of which, only one type is currently supported):

Leaderboard Type

Description

# of Milestones Reference

Singleton Leaderboard

Leaderboard defined by a single aggregation window (start / end timestamp pair).

2

When creating a leaderboard, milestones will either be referenced (read: reused) or created relative to the set of existing milestones defined by/for the user. For example, consider a Singleton Leaderboard which is defined to rank players between 08:00 - 16:00 on 10/31 over the stat total_apples_collected (SUM). Creating this leaderboard, assuming no milestones currently exist, would create the following milestones:

Leaderboards_Milestones.png

Stats produced for total_apples_collected with timestamps occurring between 08:00 and 16:00 will be aggregated together into a single sum value for each playerId. These values, for all players, will then be ranked into the Singleton Leaderboard we defined.

To highlight milestone reuse, consider next that we have another stat, total_pumpkins_collected, that we want a second Singleton Leaderboard for over this same time period. Creating this new leaderboard will reference / reuse the same milestones created for the total_apples_collected and not further reduce the number of milestones available.

Milestones are deleted by the system automatically when no leaderboards reference them.

To summarize:

  • Total Global Leaderboards: Limited by available milestones (see above)

  • Max Number of Milestones (Default): 100

  • Total Global Leaderboard entries: 1000 (+1000 overflow)

Scoring Methods

The Leaderboards Interface features multiple scoring methods to accommodate different kinds of games or ranking systems. Your leaderboard can calculate and rank scores according to a score aggregation type. You must use the same aggregation type for your leaderboard as is used by the stat that is assigned to it. The available score aggregation types are as follows:

Score Aggregation Type

Leaderboard Behavior

EOS_LSA_Min

The leaderboard uses the player's lowest reported score. The player with the lowest score holds the number one position.

EOS_LSA_Max

The leaderboard uses the player's highest reported score. The player with the highest score holds the number one position.

EOS_LSA_Sum

The leaderboard adds up every score each player reports. The player with the highest total score holds the number one position.

EOS_LSA_Latest

The leaderboard uses the player's most recent reported score. The player with the highest score holds the number one position.

Usage of EOS_LSA_Latest for leaderboards can result in volatile leaderboard entries. For example, consider a Latest stat which tracks the number of objects collected for a level. While on a previous run, a player can perform well enough to be placed on a leaderboard for this stat. A subsequent play through of the level could result in worse performance and result in the player being removed from the leaderboard. In general, we do not encourage leaderboard usage with status defined with EOS_LSA_Latest unless using it to control their stat values/aggregations directly. For example, a leaderboard containing a custom computed ELO by player. When using LATEST leaderboards it is important note that:

  1. Leaderboards only retain aggregations for the top 2000 entries and only allow the top 1000 rankings to be viewable. Values associated with players ranked 2001 and up are not retained by the system. In order for such a player to be ranked onto a leaderboard, a stat must be emitted (or remitted) for that user.

    1. LATEST stat values which vary wildly between emissions result in poor player experiences relative to (1). The ideal stat is one whose value is monotonic per player over time.

In addition, you will need to provide the name of the stat that the leaderboard will use as the score value.

Accessing Leaderboard Information

To access leaderboard information, you will need the leaderboard's ID. You can get these from the Developer Portal and add them into your game directly, or you can query the EOS SDK for a list of all leaderboards associated with your game. To do this, call EOS_Leaderboards_QueryLeaderboardDefinitions with an EOS_Leaderboards_QueryLeaderboardDefinitionsOptions struct initialized with the following information:

Property

Value

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDDEFINITIONS_API_LATEST

StartTime

An optional POSIX timestamp for the leaderboard's start time, or EOS_LEADERBOARDS_TIME_UNDEFINED

EndTime

An optional POSIX timestamp for the leaderboard's end time, or EOS_LEADERBOARDS_TIME_UNDEFINED

Once this operation completes, your callback, of type EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallback, will run with an EOS_Leaderboards_OnQueryLeaderboardDefinitionsCompleteCallbackInfo structure indicating success or failure. On success, the local cache will contain the list of leaderboards meeting your criteria. You can then use EOS_Leaderboards_GetLeaderboardDefinitionCount to see how many leaderboard definitions the system found, and call EOS_Leaderboards_CopyLeaderboardDefinitionByIndex to get a copy of each leaderboard. If you already know the ID of a specific leaderboard that you expect is in the list, you can instead call EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId to get a copy of that board's definition.

When calling EOS_Leaderboards_CopyLeaderboardDefinitionByIndex, pass in an EOS_Leaderboards_CopyLeaderboardDefinitionByIndexOptions structure initialized as follows:

Property

Value

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

When calling EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId, pass in an EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardIdOptions structure initialized as follows:

Property

Value

ApiVersion

EOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST

LeaderboardId

The ID of the leaderboard whose information you want to retrieve

In either case, you will receive a copy of the information that defines the leaderboard (type EOS_Leaderboards_Definition). When you no longer need this information, release it by calling EOS_Leaderboards_LeaderboardDefinition_Release.

Retrieving Leaderboard Data

Typically, players will want to view leaderboard data for the entire world, or just for their friends. The Leaderboards Interface provides separate querying methods to support these two ways to retrieve the data.

Retrieving Ranked Worldwide Data

To view a leaderboard's worldwide rankings, call EOS_Leaderboards_QueryLeaderboardRanks with an EOS_Leaderboards_QueryLeaderboardRanksOptions structure. Initialize the structure as follows:

Property

Value

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDRANKS_API_LATEST

LeaderboardId

The ID of the leaderboard whose information you want to retrieve

When the operation completes, your callback, of type EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallback, will run with an EOS_Leaderboards_OnQueryLeaderboardRanksCompleteCallbackInfo data structure that indicates success or failure. On success, the EOS SDK cache will contain the data you requested. You can find the number of records by calling EOS_Leaderboards_GetLeaderboardRecordCount, and get copies of individual records with EOS_Leaderboards_CopyLeaderboardRecordByIndex. If you want the record for a specific user, and you have that user's ID, you can call EOS_Leaderboards_CopyLeaderboardRecordByUserId. Both of thee functions return a copy of a cached record in the form of an EOS_Leaderboards_LeaderboardRecord. Release these copies with EOS_Leaderboards_LeaderboardRecord_Release once you no longer need them.

Retrieving Unranked Friend Data

If you want to show a player the score records for their friends, use EOS_Leaderboards_QueryLeaderboardUserScores. Call this function with an EOS_Leaderboards_QueryLeaderboardUserScoresOptions structure, initialized as follows:

Property

Value

ApiVersion

EOS_LEADERBOARDS_QUERYLEADERBOARDUSERSCORES_API_LATEST

UserIds

An array of EOS_ProductUserId values indicating the users whose scores you want to retrieve

UserIdsCount

The number of IDs contained in the UserIds parameter

StatInfo

The stats to be collected, and the sorting method to use when determining rank order for each stat

StatInfoCount

The number of elements in the StatInfo array

StartTime

An optional POSIX timestamp, or EOS_LEADERBOARDS_TIME_UNDEFINED; results will only include scores made after this time

EndTime

An optional POSIX timestamp, or EOS_LEADERBOARDS_TIME_UNDEFINED; results will only include scores made before this time

Scores that you collect in this way will be sorted according to your specification, but do not come from, or require, a leaderboard. These scores will have no global ranking. The StatInfo field includes both the stat you wish to compare and the ranking method you want to use relative to the other user scores retrieved in the query.

After the operation finishes, your callback, of type EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallback, will run with an EOS_Leaderboards_OnQueryLeaderboardUserScoresCompleteCallbackInfo data structure that indicates success or failure. If the call succeeds, the cache will contain ordered records of your friends' scores. You can get the number of records available with the EOS_Leaderboards_GetLeaderboardUserScoreCount function, and use EOS_Leaderboards_CopyLeaderboardUserScoreByIndex to retrieve scores by index, or EOS_Leaderboards_CopyLeaderboardUserScoreByUserId to retrieve them by user ID. In either case, you will receive a copy of the appropriate EOS_Leaderboards_LeaderboardUserScore data. When you no longer need this data, use EOS_Leaderboards_LeaderboardUserScore_Release to release it.

Usage Limitations

The Leaderboards Interface gives developers using 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.

For general information about throttling, usage quotas, and best practices, see Service Usage Limitations.

The following limits apply to a deployment's overall use of leaderboards:

Feature

Limitation

Number of global leaderboards

Limited by available milestones - see Leaderboards Interface

Total global leaderboard entries

1000 (+1000 overflow - see Leaderboards Interface )

Number of friend leaderboards

Unlimited, see Stats for more details.

Friend leaderboards are made by directly querying Stats; they are not affected by the global leaderboard limit.

There are also usage-rate limitations that apply on a per-user or per-deployment basis. Per-user limitations apply to individual users playing games and viewing existing leaderboards, while per-deployment limitations apply to calls that create or delete those leaderboards.

Feature

Per-User Limitation

Per-Deployment Limitation

Get a single leaderboard value

100 requests per minute

Get all leaderboard values

10 requests per minute

Create a leaderboard

100 requests per minutes

Delete a leaderboard

100 requests per minutes