Rank
A module that allows you to save player scores and show & get rankings (leaderboards).
This class is used to save player scores and show rankings for each game.
Currently, there is only one type of ranking UI, but more will be added in the future.
Methods
.saveScore(options)
Saves the player’s score to the server.
Parameters
options
(Object): An object containing the following properties:
score
(Integer): The player’s score to be saved.order
(String, optional): The order in which scores should be ranked. Can be either “ASC” (ascending) or “DESC” (descending). Defaults to “DESC” if not specified.
The score is saved as an Integer, so when designing the score system, ensure it is calculated as an Integer.
Returns
Promise: A promise that resolves when the score is successfully saved.
Examples
// Save a score with default descending order
REDBRICK.Rank.saveScore({ score: 10 });
// Save a score with descending order
REDBRICK.Rank.saveScore({ score: 10, order: "DESC" });
// Save a score with explicitly set ascending order
REDBRICK.Rank.saveScore({ score: 10, order: "ASC" });
Notes
- If the
order
parameter is not provided, the score will be saved with descending order (“DESC”). - When retrieving scores, they will be ordered according to the
order
parameter specified when saving.
It’s recommended to consistently use the same order
for all score saves within a game to ensure proper ranking.
Orders are saved separately in the database. Scores saved with order: "ASC"
can’t be retrived with show({order: "DESC"})
or vice versa,
.show(options)
Shows the ranking in the specified order. The current player’s score is shown at the top of the leaderboard.
Parameters:
options
(optional): An object with the following properties:theme
(string, optional): The visual theme for the ranking UI.type
(string, optional): The type of ranking display.order
(string, optional): The order of ranking display
Currently, there is only default type of theme
for ranking UI, but more will be added in the future.
time
option is available along with default
type. More will be added in the future
By default ranking displayed in DESC
order. Also, ASC
order is available.
Example Usage:
// Show default ranking
REDBRICK.Rank.show();
// Show ranking with custom options
REDBRICK.Rank.show({
type: "time",
});
Display ranking with time option: hh:mm:ss
REDBRICK.Rank.show({
type: "time",
});
Display the ranking in time type and descending order.
REDBRICK.Rank.show({
type: "time",
order: "DESC"
});
.hide()
Hides the ranking. Once the ranking is shown, other GUIs cannot be clicked until it is closed by pressing the close (X) button. You can use setTimeout()
to automatically hide the ranking after a few seconds if desired.
Example
// This Button shows the ranking
this.onClick(() => {
REDBRICK.Rank.show();
});
// This Function saves the score as Integer.
function onGameEnd() {
// ...
REDBRICK.Rank.saveScore(score);
}
You can use .hide()
as follows
// This Button shows the ranking and hides after 1 sec
this.onClick(() => {
REDBRICK.Rank.show();
setTimeout(() => {
REDBRICK.Rank.hide();
}, 1000);
});
Fetching My Rank
getMyRank()
An asynchronous function that retrieves the current user’s rank information.
async function fetchMyRank() {
const myRank = await REDBRICK.Rank.getMyRank();
return myRank;
}
getMyRank() is asynchronous function and should be used with await or .then().
Return Value:
Returns a JSON object with the user’s rank information, or an empty object if the score doesn’t exist.
Example Response:
{
"id": 21,
"pid": "pid of the game",
"score": 24,
"rank": 1,
"username": "username",
"avatar": "avatar_url"
}
Fetching All Ranks
getAllRank(options)
An asynchronous function that retrieves the ranking information for all users.
async function fetchAllRanks() {
// fetches 100 top users by default when options isn't passed
const allRanks = await REDBRICK.Rank.getAllRank();
return allRanks;
}
getAllRank() is asynchronous function and should be used with await or .then().
Parameters:
options
(optional): An object with atake
property to specify the number of top ranks to retrieve. Default is 100.
Example Usage:
// Fetch top 10 ranks
const top10Ranks = await fetchAllRanks({ take: 10 });
Return Value:
Returns an array of JSON objects, each containing a user’s rank information.
Example Response:
[
{
"id": 21,
"pid": "pid of the game",
"score": 24,
"rank": 1,
"username": "username",
"avatar": "avatar_url"
},
{
"id": 22,
"pid": "pid of the game",
"score": 21,
"rank": 2,
"username": "username2",
"avatar": "avatar_url"
},
// ... more rank entries
]