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.

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.

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.

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):

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)

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:

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

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:

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:

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

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.

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.

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

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.

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:

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:

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.