Introduction to Leaderboards
Overview
The AccelByte Leaderboard service enables a sense of competition among players, which can motivate them to play harder to improve their performance, and try to move up the ranking. The Leaderboard service uses the data stored in AccelByte Statistics, to compare each player's rank.
In this section, you will learn about the key concepts of the Leaderboard service, and best practices when utilizing the service.
Key Concepts
It is important to understand some key concepts.
Leaderboard Configuration
The Leaderboard Configuration provides you a way to set up a Leaderboard with a specific context and purpose, to match the requirements of your game. Each configuration allows you to choose what values will be compared and drawn from Statistics, and to set up the start and end date, and the Leaderboard lifecycle.
Leaderboard Code
Instead of using machine generated codes, the Leaderboard code is a unique string used to identify a Leaderboard.
Example Leaderboard codes:
- "mmr"
- "victory"
- "experience"
Statcode
Statcode is an identifier from a Statistics configuration that the Leaderboard draws from. Statistic configurations store players' scores and it can be used by the Leaderboard to rank players. Make sure you have created a Statistic configuration in the same game namespace, prior to enabling your Leaderboard.
Leaderboard Life Cycle
Players compete against each other to earn points during the designated period, and their progress is tracked and displayed on the Leaderboard.
A Leaderboard can have one of five life cycles:
All Time
The All-Time Leaderboard doesn't have any time constraints, it will rank players based on their final value from players' statistic data. As player scores continue to accumulate, this leaderboard will be updated.
Daily
Daily Leaderboards rank players based on their performance over a 24-hour period. The game admin can set the start time. The Leaderboard resets after 24 hours and players then have a new chance to compete for a spot on the Leaderboard in the next 24-hour period.
Weekly
Weekly Leaderboards rank players based on their performance over a 7-day period. The game admin can set the start date and time for the period. The Leaderboard resets after 7 days and players then have a new chance to compete for a spot on the Leaderboard the following 7 days.
Monthly
Monthly Leaderboards rank players based on their performance over a month. The game admin can set the start date and time. The Leaderboard resets at the same time and date of the following month and players then have a new chance to compete for a spot on the Leaderboard in the following month.
Seasonal
Seasonal Leaderboards rank players based on their performance during a specific custom period of time. In this type of Leaderboard you set both the start time, and end time.
Start Date
The exact time when the Leaderboard starts receiving published values from the statistics service, that will be compared and ranked.
Order
Order allows you to choose whether the Leaderboard will be displayed ascending or descending.
Leaderboard Update Flow
This section explains how the Leaderboard service is integrated with User Statistics. Understanding the flow below will make it easier for you to understand how to best use the service.
The Leaderboard service listens for specific Statistics events. Every time a user statistic is updated, Statistics will publish an event that will be picked up by the Leaderboard service. The data in the event will be added to the Leaderboard, and user ranking sorted.
Leaderboard Version
We're supporting a new version of Leaderboard to enhance your experience with our services.
New Leaderboard
- For new users, the legacy version will not be accessible on the Admin Portal. You can only create configurations in the new Leaderboard version. Use the v3 endpoints.
- For existing users that still use the legacy version of Leaderboard, if you're eager to explore the latest enhancements, upgrade your Leaderboard by creating a configuration in the new Leaderboard menu and use the v3 endpoints for the newest version.
Refer to Display leaderboard ranking for more information on displaying players' rankings using the new version of Leaderboard.
Legacy Leaderboard
You can continue to use the legacy version using the v1 and v2 endpoints. They are still fully functional and you can still access your existing configurations from the Admin Portal. However, be advised that the updates and improvements for these versions have ceased.
For more information on the legacy leaderboard versions, refer to their guides for creating a leaderboard configuration and displaying players' rankings.