PlayerIO

The fastest way to build online games without breaking a sweat.

Multiplayer Reference

Multiplayer  class documentationClass Leaderboards

Namespace: PlayerIO.GameLibrary
Language: C# / .NET

The Player.IO Leaderboard service

To use Leaderboards in your game, you must first setup at least one Leaderboard Group. Each group needs an identifier, for example "score" or "laptime", and you need to set the sort order and deletion policy for the group.

A group can then contain one or more leaderboards, where each leaderboard is a sorted list of players by their score, sorted by the sort order of the group. If you leave the leaderboard identifier empty, PlayerIO will use the default leaderboard for the group. A leaderboard is automatically created by setting a player's score for a given leaderboard in a group, and you can use this to automatically have for example monthly leaderboards that "reset" each month

Note that the top player of a leaderboard has rank #1, while all get operations are 0-indexed.

Here's how to set a player's score in the default leaderboard of the group "score":

Here's how to set a player's score in a monthly rotating leaderboard of the group "score":

Here's how to get the number of players in a default leaderboard:

Here's how to get the top 10 players in a default leaderboard:

By using the Count method you can find out how many entries there are in the entire leaderboard, and you can get the second page of 10 players by increasing the index parameter:

If you want to get the rank and score of a single player, pass in the connectuserid as a filter:

You can pass in multiple connectuserids to get a filtered list of only those players. For example, by passing in a list of friends of the current player, you can get a toplist for the friends. Don't forget to also pass in the connectuserid of the current player if you want his position as well:

The GetTop method starts at the top of the leaderboard, but if you want to know which players are immediately surrounding the current player, use the GetNeighbourhood method. The index parameter can be either positive or negative. If you use a negative number, the results will start above the current player, with better players, player who have a lower rank than the current player, and a better score. An index of 0 means the current player, and a positive index means that you start below the current player, with worse player, players who have a higher rank, and a worse score. For example, to get the 5 players above the current player, the current player himself, and the 5 players directly below, you can do this:

Finally, GetNeighbourhood also takes a list of players that you can use to filter the results, but unlike GetTop, the current player is always automatically included in the filter list. For example, if you have a long list of friends, but want to know which friend is immediately above the current player in the leaderboard, and which friend is immediately below the current player, you can do something like this:

Methods

 
public void
Count (string group, string leaderboard, Callback<int> successCallback)

Gets the number of entries in a leaderboard

public void
Count (string group, string leaderboard, Callback<int> successCallback, Callback<PlayerIOError> errorCallback)

Gets the number of entries in a leaderboard

public void
GetNeighbourhood (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback)

Gets the neighbourhood of entries of a leaderbord around the current user.

public void
GetNeighbourhood (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback, Callback<PlayerIOError> errorCallback)

Gets the neighbourhood of entries of a leaderbord around the current user.

public void
GetTop (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback)

Gets the top entries of a leaderbord.

public void
GetTop (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback, Callback<PlayerIOError> errorCallback)

Gets the top entries of a leaderbord.

public void
Set (string group, string leaderboard, Int64 score, Callback<LeaderboardEntry> successCallback)

Sets the score for a user on a leaderboard.

public void
Set (string group, string leaderboard, Int64 score, Callback<LeaderboardEntry> successCallback, Callback<PlayerIOError> errorCallback)

Sets the score for a user on a leaderboard.

Leaderboards.Count

public void
Count (string group, string leaderboard, Callback<int> successCallback)

Gets the number of entries in a leaderboard

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
Callback<int> successCallback
Callback that will be called when the operation succeeds.

Leaderboards.Count

public void
Count (string group, string leaderboard, Callback<int> successCallback, Callback<PlayerIOError> errorCallback)

Gets the number of entries in a leaderboard

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
Callback<int> successCallback
Callback that will be called when the operation succeeds.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the operation.

Leaderboards.GetNeighbourhood

public void
GetNeighbourhood (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback)

Gets the neighbourhood of entries of a leaderbord around the current user.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
int index
What index to start getting entries from. An index of 0 starts at the user. A negative index starts that many entries above the user, and a positive index starts below the user.
int count
How many leaderboard entries to get. The max number of entries that can be retrieved per call is 1000.
String[] filterUserIds
An optional list of users to filter the results by. For example, if you pass in a list of the user's friends, you could get the 10 closest friends above the user.
Callback<LeaderboardEntry[]> successCallback
Callback that will be called when the operation succeeds. Contains the loaded list of leaderboard entries.

Leaderboards.GetNeighbourhood

public void
GetNeighbourhood (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback, Callback<PlayerIOError> errorCallback)

Gets the neighbourhood of entries of a leaderbord around the current user.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
int index
What index to start getting entries from. An index of 0 starts at the user. A negative index starts that many entries above the user, and a positive index starts below the user.
int count
How many leaderboard entries to get. The max number of entries that can be retrieved per call is 1000.
String[] filterUserIds
An optional list of users to filter the results by. For example, if you pass in a list of the user's friends, you could get the 10 closest friends above the user.
Callback<LeaderboardEntry[]> successCallback
Callback that will be called when the operation succeeds. Contains the loaded list of leaderboard entries.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the operation.

Leaderboards.GetTop

public void
GetTop (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback)

Gets the top entries of a leaderbord.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
int index
What index to start getting entries from. An index of 0 starts at the user with rank #1, an index of 100 starts at the user with rank #101, etc.
int count
How many leaderboard entries to get. The max number of entries that can be retrieved per call is 1000.
String[] filterUserIds
An optional list of users to filter the results by. For example, if you pass in a list of the user's friends, you could get the 10 best friends, and their absolute rank.
Callback<LeaderboardEntry[]> successCallback
Callback that will be called when the operation succeeds. Contains the loaded list of leaderboard entries.

Leaderboards.GetTop

public void
GetTop (string group, string leaderboard, int index, int count, String[] filterUserIds, Callback<LeaderboardEntry[]> successCallback, Callback<PlayerIOError> errorCallback)

Gets the top entries of a leaderbord.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
int index
What index to start getting entries from. An index of 0 starts at the user with rank #1, an index of 100 starts at the user with rank #101, etc.
int count
How many leaderboard entries to get. The max number of entries that can be retrieved per call is 1000.
String[] filterUserIds
An optional list of users to filter the results by. For example, if you pass in a list of the user's friends, you could get the 10 best friends, and their absolute rank.
Callback<LeaderboardEntry[]> successCallback
Callback that will be called when the operation succeeds. Contains the loaded list of leaderboard entries.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the operation.

Leaderboards.Set

public void
Set (string group, string leaderboard, Int64 score, Callback<LeaderboardEntry> successCallback)

Sets the score for a user on a leaderboard.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
Int64 score
The score to set for the user.
Callback<LeaderboardEntry> successCallback
Callback that will be called when the operation succeeds.

Leaderboards.Set

public void
Set (string group, string leaderboard, Int64 score, Callback<LeaderboardEntry> successCallback, Callback<PlayerIOError> errorCallback)

Sets the score for a user on a leaderboard.

Arguments

string group
The identifier of the leaderboard group.
string leaderboard
The identifier of the specific leaderboard in the group, or null for the default leaderboard.
Int64 score
The score to set for the user.
Callback<LeaderboardEntry> successCallback
Callback that will be called when the operation succeeds.
Callback<PlayerIOError> errorCallback
Callback that will be called instead of successCallback if an error occurs during the operation.