Leaderboards is a system for creating and managing scores and rankings in your game. Although BigDB can be used to track scores, and BigDB indexing allows you to show global toplists, it's not possible to get the rank or position of a given player on that toplist. This is where the Leaderboards system comes in.
The Leaderboards feature allows you to store the score of a player on a leaderboard, and immediately know which rank, i.e. which position on the leaderboard that player now has. Given a leaderboard, you can quickly load and page through the top players and their scores and ranks, but you can also load and page through the neighbourhood of scores around a given player. Another feature allows you to restrict the results to a list of players, which means you can quickly and easily display a list of a player's friends, what score they have, and how they rank globally compared to each other.
Leaderboards are organized into groups, which you create in the PlayerIO admin panel. A group defines the sort order of all leaderboards in the group, and also an optional deletion policy. If you choose a descending sort order for your group, the player with the highest score will be the highest ranked player, that player will be #1. If you choose ascending sort order, then the player with the lowest score will be #1.
If you only make a single leaderboard for your game, a problem is that over time, the top players will stagnate and your leaderboard might show players who aren't really playing your game anymore. It's therefore a good idea to "reset" your leaderboards regularly, to give active players a chance at the top spots. The actual leaderboards within a group are created simply by using the library to write a score to a given group and leaderboard. If the leaderboard doesn't yet exist, it will automatically be created. So by having a date or month or other datetime part of your leaderboard identifier, your game can automatically create new leaderboards for every day, week, month, or whatever arbitrary time period you wish.
If you just want a single global forever leaderboard for your game, you can leave the leaderboard identifier empty in your calls, and the score will simply be stored on the default leaderboard for the group.
Since there is a limit on the number of allowed entries across all your leaderboards, the deletion policy of a group allows you automatically remove old leaderboards. The Leaderboards feature keeps track of when each individual leaderboard was created, and when a score was last written to it, so just choose a deletion policy that ensure you keep enough old leaderboards around as your game needs. For example, if noone in your game cares about the monthly leaderboard of six months ago, select "Six Months After Creation", and any older leaderboard will automatically be deleted.
When loading leaderboard data from PlayerIO, you have to specify an index and a count for each call. This allows you to fetch a specific number of entries, and to page through the leaderboard. When using the GetTop method, it's 0-indexed based on the top player, which means that if you pass in an index of 0 and a count of 10, you will get the top 10 players of the leaderboard, the players with rank #1 to rank #10. If you pass in an index of 10, you will start with the player with rank #11, etc.
The GetNeighbourhood method also retrieves lists of entries, but index 0 means the current player, a negative index means players with a better rank than the current player, and a positive index means players with a worse rank than the current player. For example, if the current player has rank #4711 on a leaderboard, if you pass in an index of -2 and a count of 5, you will retrieve the players with ranks #4709 to #4713.
No Get method will ever return an error if you are out of bounds. For example, if you attempt to get the top 100 players of a leaderboard, but there are only 57 players on it yet, you'll simply get back a list of those 57 entries.
Both the GetTop method and GetNeighbourhood method take an optional list of connectUserIds as a filter. This allows you to restrict the display of a leaderboard to for example only the player's friends, or the player's guild, or any other arbitrary group of players. The indexing works exactly as before, but on the given subset of users. So passing in an index of 0 and a count of 5 returns the top five ranked players on that list, and their global ranks and scores.
By passing in a single connectUserId as a filter, you can retrieve the current global rank and score of that user.