Leaderboards Interface

Interface to handle online leaderboards

10 mins to read

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 TypeDescription# of Milestones Reference
Singleton LeaderboardLeaderboard 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:

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 TypeLeaderboard Behavior
EOS_LSA_MinThe leaderboard uses the player's lowest reported score. The player with the lowest score holds the number one position.
EOS_LSA_MaxThe leaderboard uses the player's highest reported score. The player with the highest score holds the number one position.
EOS_LSA_SumThe leaderboard adds up every score each player reports. The player with the highest total score holds the number one position.
EOS_LSA_LatestThe leaderboard uses the player's most recent reported score. The player with the highest score holds the number one position.

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, which is the same as the leaderboard's name in the Developer Portal. 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:

PropertyValue
ApiVersionEOS_LEADERBOARDS_QUERYLEADERBOARDDEFINITIONS_API_LATEST
StartTimeAn optional POSIX timestamp for the leaderboard's start time, or EOS_LEADERBOARDS_TIME_UNDEFINED
EndTimeAn 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:

PropertyValue
ApiVersionEOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYINDEX_API_LATEST

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

PropertyValue
ApiVersionEOS_LEADERBOARDS_COPYLEADERBOARDDEFINITIONBYLEADERBOARDID_API_LATEST
LeaderboardIdThe 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:

PropertyValue
ApiVersionEOS_LEADERBOARDS_QUERYLEADERBOARDRANKS_API_LATEST
LeaderboardIdThe 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