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 appropriate 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 leaderbord 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

Each leaderboard uses a specific stat as the score that it tracks. See the Stats Interface for more information.

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.

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

Please consult the Service Usage Limitations page for information about usage limits that you should observe to maintain performance and speed.