11. Leaderboard
For pure client games without their own servers, and wish to provide leaderboards for encouraging competition, the SDK provides leaderboard mechanism for developers to keep track of these data.
※Be aware that the storage functions aren't secure. If security is a concern please use your own backend server to store data.
※ This function is available since SDK version 3.0.4
11.0.1. Description
Leaderboard provides three functions:
All functions of the leaderboard are executed asynchronously and return a Promise object.
11.1. Default and custom leaderboards
Each game can have a default leaderboard and any number of custom leaderboards. The APIs for each leaderboard are the same.
11.1.1. Obtain the default leaderboard:
let leaderboard = wakool.leaderboard;
11.1.2. Obtain a custom leaderboard:
let orcsBoard = wakool.getLeaderboard('orcs_camp');
11.2. Get top N
Get the top N entries of a leaderboard:
wakool.leaderboard.top(limit = 50, order = 'desc');
Parameters:
name | type | description |
---|---|---|
limit |
integer | Maximum entries returned. Not required, default value is 50 |
order |
desc or asc |
Sort order. Not required, default is desc (descending order) |
Example:
wakool.leaderboard.top(10).then(results => {
results.forEach(result => console.log(result));
});
Response:
The function top()
asynchronously returns an array
contains 0 to limit
rerults, each with the following fields:
name | type | description |
---|---|---|
score |
integer | The score of the player |
description |
any | Optional data that was set with the score in setScore |
user_id |
integer | The wakool id of the player |
nickname |
string | The nickname of the player or undefined if unavailable |
user_pic |
string | The URL of the player's avatar or undefined if unavailable |
create_datetime |
Date | Time of the player's record being created |
modify_datetime |
Date | Time of the player's record being updated |
11.3. Update current user's score
To update the score of the current player:
wakool.leaderboard.setScore(score, description = null, constraint = 'increase_only');
Parameters:
name | type | description |
---|---|---|
score |
integer | The score to be updated |
description |
any | Optional data that will be returned together with the score |
constraint |
increase_only or decrease_only |
Update condition. Not required, default value is increase_only which means data will only be updated if the score is greater than the previous value if one exist. |
Example:
wakool.leaderboard.setScore(10350, '{level: 20}').then(result => {
console.log(result.updated ? 'Score updated' : 'Score not updated');
});
11.4. Get current user's score
To get the score of the current player:
wakool.leaderboard.getScore();
Example:
wakool.leaderboard.getScore().then(function(result) {
console.log('My score is ' + result.score);
});
Response:
The function getScore()
asynchronously returns the current player's score in the leaderboard, the data structure is the same with the entries of the response from top()
with the following fields:
name | name | description |
---|---|---|
score |
integer | The score of the current player in the leaderboard |
description |
any | Optional data that was set with the score in setScore |
user_id |
integer | The wakool id of the current player |
nickname |
string | The nickname of the current player or undefined if unavailable |
user_pic |
string | The URL of the current player's avatar or undefined if unavailable |
create_datetime |
Date | Time of the current player's record being created |
modify_datetime |
Date | Time of the current player's record being updated |