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.
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:
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.
Total Global Leaderboards: Limited by available milestones (see above)
Max Number of Milestones (Default): 100
Total Global Leaderboard entries: 1000 (+1000 overflow)
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|
|The leaderboard uses the player's lowest reported score. The player with the lowest score holds the number one position.|
|The leaderboard uses the player's highest reported score. The player with the highest score holds the number one position.|
|The leaderboard adds up every score each player reports. The player with the highest total score holds the number one position.|
|The 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:
|An optional POSIX timestamp for the leaderboard's start time, or |
|An optional POSIX timestamp for the leaderboard's end time, or |
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.
EOS_Leaderboards_CopyLeaderboardDefinitionByIndex, pass in an
EOS_Leaderboards_CopyLeaderboardDefinitionByIndexOptions structure initialized as follows:
EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardId, pass in an
EOS_Leaderboards_CopyLeaderboardDefinitionByLeaderboardIdOptions structure initialized as follows:
|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
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:
|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:
|An array of |
|The number of IDs contained in the |
|The stats to be collected, and the sorting method to use when determining rank order for each stat|
|The number of elements in the |
|An optional POSIX timestamp, or |
|An optional POSIX timestamp, or |
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.
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:
|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|