Dynamic Leaderboards

[novabyte]

Define leaderboards on-demand via the script runtime with optional reset schedules (daily/weekly/monthy/etc). Form hierarchies of leaderboards for league-style progression system. This depends on TTL support in cockroachdb.

[novabyte]

Some functionality we should offer with the leaderboards impl:

• Each leaderboard entry should have metadata which can store custom game-specific properties.
• Leaderboard resets should activate a background job in the Lua runtime which can be used to efficiently iterate over records and operate on the results. Either to distribute rewards or affect the game behaviour for the user in some way.
• Leaderboards which expire (after some daily/weekly/monthly reset) should be retained so it can be operated on for business intelligence etc.
• Leaderboards should be filterable by region (or country) and other properties.
• If possible it should be easy to get the full count of users on the leaderboard (even if it is an approx.). This is complicated because databases generally do not track counts on records. We'll have to investigate the best approach with cockroachdb.
• Lookup a specific user on the leaderboard. This could be the current user or any other user. For example to find your friend on a global leaderboard.
• Create leaderboards for just friends or group members.
• Hide specific users from a leaderboard (for ban purposes).
• Delete entries in a specific leaderboard. This would be reserved as an admin task for cleanup and development.

[novabyte]

Design update

This work is part of the 0.12.0 development:

• Leaderboards can be defined on the fly. No pre-configuration needed. They can be created via a Lua runtime function either at startup (CREATE IF NOT EXISTS semantics) or on-demand. They can also be setup via a Nakama subcommand. i.e. nakama admin create-leaderboard --sort-order=desc
• The owner ID of a leaderboard entry does not need to be a user ID - it can be used with groups to create guild leaderboards.
• All leaderboards will be single-entry per user rather than "arcade style" where multiple entries for a user could exist. If arcade style leaderboards are required they can be added later or via the Lua runtime.
• Leaderboards can be retrieved in ASC or DESC result order by score.
• A user can perform a "haystack" query to find their position in a leaderboard with the users around them. This is useful when a user is somewhere in the middle of a large set of entries.
• Score submissions can be absolute so they overwrite any previous score. This enables users to move both up and down a leaderboard based on their own score submission.
• Each leaderboard entry can contain metadata (as JSON) which could store additional game specific stats alongside the score.
• A user can view a specific collection of IDs on the leaderboard. This can be used to create Friend or Group leaderboards. It can also be used to create any kind of social leaderboard view.
• Filter leaderboards by a number of fields stored with an entry (but not in metadata).
• Leaderboards can be configured with a reset schedule.
• Leaderboard entries will be rank calculated for the top 1024 records. In future we may use a sampling technique to approx. ranks on the rest of the dataset for each leaderboard.
• A game client can list all available leaderboards which are not "locked".
• A new leaderboard entry will store the number of updates made. This can be useful for some kinds of gameplay and is also useful to track cheaters.
• A new leaderboard entry can be submitted with one of a number of operators: INCR, DECR, SET, and BEST. These operators define how the submitted score value is applied to the value in the database.
• A new leaderboard entry can be checked against a score delta which ensures that the update can only be within the range of values for it to be applied. This does not apply with the SET operator. More advanced velocity checks on values should be done via the Lua runtime.
• It will be possible to get a collection of leaderboard entries from a number of leaderboard IDs in one request. This is useful to build a "stats view" for a user.

These features depend on https://github.com/heroiclabs/nakama/issues/5:

• Rank calculations on all leaderboard entries. These will be done asynchronously by a resource controlled worker pool across a cluster. This requires the background jobs system which is part of the Lua runtime work.
• Reward distribution from leaderboards will require reward scripts to be executed in a server authorititative way as part the background jobs system.
• A leaderboard can be locked to indicate game clients cannot submit to it. It can only be updated per user via the Lua runtime.
• ELO style leaderboards will not be directly supported but can be achieved with the Lua runtime used to provide the score calculation algorithm.

These features are deferred for the future:

• An approximate count of a leaderboard will be maintained in future.
• A leaderboard can be "linked" with another leaderboard to form hierarchies. This can easily be performed via the Lua runtime until we add first-class support for it.
• A user who's been shadow banned on a leaderboard will see their score but no other users will see it.
• An admin task will be added (perhaps as part of a subcommand) so specific entries on the leaderboard can be banned or deleted.

[zyro]

We can implement "arcade style" leaderboards through authoritative boards managed by the Lua runtime. Leaderboard entry owner IDs don't need to be user IDs so a Lua script can set them to a combination of user ID and a unique factor, resulting in multiple entries per user.

Rank calculations will still work as expected.

[novabyte]

Resolved in https://github.com/heroiclabs/nakama/commit/14cbcc78bed32d4a1fb4ba8e53584a7b6023b805.

Some final notes on dynamic leaderboards:

• Leaderboards can be created via nakama admin create-leaderboard --sort=desc. See full command for all options.
• They can be ASC or DESC sort order on scores.
• Various "op codes" can be used to specific how a score update is applied to the record.
• A record can contain additional JSON metadata. There's also official fields like lang, location, and timezone which can be filtered on.
• The owner of a leaderboard record can be a user or some other game object. For example a group ID for guild leaderboards.

The documentation will cover all usage notes.

• Rank calculations will be handled as part of the script runtime.
• Hierarchical leaderboards can be built via the script runtime.

[codedrunk]

• Leaderboards should be filterable by region (or country) and other properties.

@novabyte Hi. Has this been implemented?

[FaisalZaheer]

Are these features implemented ?

[novabyte]

@FaisalZaheer Yes, these features were all implemented. The feature was scoped down in Nakama 2.0 due to lack of use by game teams. Please ask questions on the community forums. Thanks 🙏