Leaderboards are where you record and/or retrieve your player rankings and scores. There are different types of leaderboards that offer different features, but they all track your players' scores.
One thing to note about leaderboards is that they track scores for several different time spans. This allows you to use the same leaderboard to track rankings for various time spans. The currently supported time spans are as follows:
Whenever a score is recorded, it is recorded for each of the aforementioned timespans. So, when a score is recorded, the all-time time span for the leaderboard is updated, as are the daily, weekly, monthly, and yearly time spans for the leaderboard for the specific day, week, month, and year that correspond to the recording's date/time.
This powerful feature allows you to easily retrieve and display rankings for any given day, week, month, or year for which scores have been recorded as well as the all-time rankings.
Leaderboards have the following properties:
There are currently three types of leaderboards supported in r4nkt. A leaderboard's type can be found in its
type property and can have one of the following values:
standard: This type of leaderboard is one based on players' achievement points. Whenever an achievement is earned, then the points for all of their earned achievements are added together and recorded. This is done automatically and for each time span. No other customization is required.
session: This type of leaderboard is nearly identical to the
standard type. The difference is that it only reflects achievement points that have been earned within the context of a session.
custom: A custom leaderboard is one where the players' scores must be uploaded directly. When a player's score is submitted for a custom leaderboard, then it will be compared to the player's old score on that leaderboard, if it exists. If none exist, then the new one will be recorded. If the new one is better than the old one, then the new one will be added and the old one will be forgotten. This is done for each time span. Again, no other customization is required.
For session-based leaderboards (
type is set to
session), a custom session ID is required. This ID is used when reporting activity if the activity took place within some sort of custom session. Whenever activity is reported when a custom session ID is provided, then those activities will be processed within such a context first.
ordering property determines how the scores are interpreted as well as how rankings are determined. It can have one of the following values:
larger-is-better: These leaderboards consider larger scores as better than lower ones.
smaller-is-better: These leaderboards consider smaller scores as better than larger ones.
score_preference property determines how new scores are compared to old scores when updating a given leaderboard. This applies to all leaderboard types and is applying the same regardless of the leaderboard's
score_preference can be set to one of the following values:
prefer-higher: When comparing a new score to an old one, the new one will be added if it's greater than the old one.
prefer-lower: When comparing a new score to an old one, the new one will be added if it's less than the old one.
prefer-first: The first score will be added. All subsequent scores will be ignored.
prefer-last: Each score that is submitted will added. Any previous scores will be removed.
Of course, a leaderboard is somewhat boring without the ability to see how the players are ranked.
Leaderboard rankings can be requested for any leaderboard. Pagination is supported and rankings can be requested for any given time span, which defaults to
An individual player's ranking for a specified leaderboard is also available. It can be requested for any given time span, but it defaults to