Rank player scores using leaderboards

Rajen Kishna, Technical Account Manager, Epic Games |
January 18, 2022
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)

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.
 
Developer Portal Client Policy Leaderboards
Leaderboards Client Policy allowed features and actions

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.
 
Developer Portal Leaderboards
Leaderboards in the Developer Portal

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:
  • We’ll have two separate ListViews in our UI for Leaderboards, one to display all the definitions, and one to display all the entries (or ranks) for the selected leaderboard. For now, we just have the one leaderboard, which will only occupy part of the UI.
  1. Open LeaderboardsView.xaml.cs to attach the ViewModel and hold the placeholder selection changed event handler:
  1. Add a LeaderboardsViewModel.cs class to the ViewModels folder:
  1. Add a reference to LeaderboardsViewModel in ViewModelLocator.cs:
  1. Add a LeaderboardsService.cs class to the Services folder to hold the definition query logic:
  1. Add a LeaderboardsQueryDefinitionsCommand.cs class to the Commands folder:
  1. Open LeaderboardsViewModel.cs to declare and instantiate the command:
  1. Add the following line to the RaiseConnectCanExecuteChanged() method in ViewModelLocator.cs to ensure we can only call Leaderboards APIs after successfully logging in through the Connect Interface:
  1. Lastly, add the LeaderboardsView to our TabControl in MainWindow.xaml:
Now when we run the app and authenticate through Auth and Connect, we can navigate to the Leaderboards tab and query the leaderboard definitions using the Query definitions button.
 
App Leaderboards QueryDefinitions
Leaderboard definitions queried

Querying leaderboard ranks

Now that we can query our leaderboard definitions, we can retrieve the individual entries (or ranks) of each leaderboard:
 
  1. Open LeaderboardsView.xaml and add our second ListView right below the previous </ListView> tag:
  1. Open LeaderboardsViewModel.cs and declare the following collection below the Leaderboards to hold ranks:
  1. Open LeaderboardsService.cs and add the following method to hold our rank query logic:
  1. Add a LeaderboardsQueryRanksCommand.cs class to the Commands folder:
  1. Open LeaderboardsViewModel.cs to declare and instantiate the command:
  1. Open LeaderboardsQueryDefinitionsCommand.cs to clear the ranks when we retrieve the definitions. Add the following to the Execute() method above the LeaderboardsService.QueryDefinitions() call:
  1. Open LeaderboardsView.xaml.cs and add the following line to the LeaderboardsListView_SelectionChanged event handler, so we can only query ranks after we have selected a leaderboard:
Now we can launch our app again and use the Query definitions button to retrieve the leaderboard definitions, after which we can select an individual leaderboard and use the Query ranks button to retrieve its ranks. If you don’t see any ranks, make sure to use the Stats functionality we implemented in the previous article to ingest a stat first.
 
App Leaderboards QueryRanks
Leaderboard ranks queried

Get the code

Get the code for this article below. Follow the Usage instructions in the GitHub repo to set up the downloaded code.
 
Next up, we’ll look into Epic Online Services Achievements, which can either be automatically unlocked based on Stats, or manually through the API.

The full list of articles in this series can be found in the series reference. For feedback or questions, head over to the Community forum.

    We succeed when you succeed

    Epic believes in an open, integrated games community.
    By offering our online services to everyone for free, we aim to empower more developers to serve their own player communities.