Rank player scores using leaderboards

Last week we looked at the Stats interface, which we saw provides the basis for Leaderboards in Epic Online Services. Leaderboards can be used to rank the stats that are collected to give you an easy way to expose rankings to your players, based on a specific time period. Today, we take a closer look at implementing leaderboards and go over:
 

• Usage limitations (and milestones)
• Changing our Client Policy
• Creating leaderboards in the Dev Portal
• Querying leaderboard definitions
• Querying leaderboard ranks
• Get the code

Usage limitations (and milestones)

As with the other services we’ve looked at, the Leaderboards feature has some usage limitations in place to ensure reliability and availability for all users. At the time of writing, these are the limitations (be sure to check the documentation for the most up-to-date information):

• Total number of global leaderboards is limited by available milestones (see below)
• 100 total milestones maximum per deployment
• 1000 (+1000 overflow) entries per leaderboards
  • We do not track the entire global leaderboard, we only keep track of the top 1000 scores plus an additional 1000 overflow scores in case you choose to delete entries (due to cheating, for example).

Additionally, there are per-user or per-deployment rate limits for API calls for client or server calls respectively, which you can find in the documentation.

To understand the limitations on the number of global leaderboards, we have to first understand the concept of milestones. Milestones are connected to Stats and represent a point in time. In short, you’re limited to 100 unique timestamps across the start and end dates of all your leaderboards.

Let’s say we don’t have any leaderboards created yet, and we create a new leaderboard with a start date of January 18, 2022, 9 AM and an end date of January 19, 2022, 5 PM. That would occupy two milestones of our total 100 allocation. If we add another leaderboard with a start date of January 18, 2022, 9 AM and an end date of January 20, 2022, 5 PM, however, that would only occupy one additional milestone in our allocation, as we’re re-using the January 18, 2022, 9 AM milestone.

Leaderboards with no end date (set to never expire) will only occupy one milestone at a maximum. Lastly, milestones are automatically deleted when there are no more leaderboards referencing them.

Changing our Client Policy

To use Leaderboards, we must first add actions to our Client Policy:

1. Log in to the Developer Portal at https://dev.epicgames.com/portal/.
2. Navigate to your product > Product Settings in the left menu and click on the Clients tab in the product settings screen.
3. Click on the three dots next to the client policy you’re using and click on Update policy.
4. Scroll down to Features and click on the toggle button next to Leaderboards.
5. Tick the boxes next to the “readLeaderboard” and “findLeaderboards” actions.
   • The “findLeaderboardDefinitons” action will enable us to query all leaderboard definitions and the “findLeaderboardEntries” action will enable us to retrieve the ranks for an individual leaderboard.
6. Click Save & Exit to confirm.

 

Creating leaderboards in the Developer Portal

Leaderboards are created in the Developer Portal and rely on a Stat based on one of the four aggregation types: SUM, LATEST, MIN, or MAX.

It’s important to note here that leaderboards based on a stat of the LATEST aggregation type can yield very volatile results. For example, if you set up a leaderboard to track level completion times, players can overwrite their “best” score easily using the LATEST aggregation type. In general, you should only use stats using the LATEST aggregation type in very specific scenarios.

Another important thing to note is that stat values that are ingested outside the start and end time frame of a Leaderboard will not be incorporated in the Leaderboard.

Let’s define one leaderboard for each aggregation type, except LATEST, so we can see their behavior in our sample app.
 

1. Navigate to your product > Game Services > Leaderboards in the left menu.
2. Here we can see any existing leaderboards for each deployment we have set up for our product. Select the deployment you’re using in the sample app and click on the blue “Create Leaderboard” button at the top-right of the screen.
3. Enter a Leaderboard Name of “SumLeaderboard” and select the “SumStat(SUM)” stat we created in the previous article as the Stat. For now, we’ll create all three leaderboards as never expiring by enabling the “Never expire this Leaderboard” toggle, but note that you can define a specific timespan here, based on your milestone planning explained above.
4. Click on the blue “Create” button to finalize its creation.
5. Repeat step three for the MinStat and MaxStat stats, naming the leaderboards “MinLeaderboard” and “MaxLeaderboard” respectively.

 
Note the connection icon in the top right corner next to the Search button. Clicking this will let us inspect which Leaderboards and Achievements our Stats are connected to. For now, we won’t see anything here, but we’ll revisit this in our upcoming Leaderboards and Achievements articles.

The last thing to note is the “Reset Player Stats” button next to the blue “New Stat” button. This will show us a flyout where we can search for a player by their PUID and reset any of their individual stats without affecting the stat definition itself.

Querying leaderboard definitions

Now let’s start implementing the code to query our leaderboard definitions:
 

1. Create a new User Control in the Views folder called LeaderboardsView: