Scoped Leaderboard
Overview
Scoped leaderboards help separate records into different scopes. All scopes are stored by variant name. The name can be anything.
A few use cases and example tags for saving points:
- Levels. Custom rating for each level.
LEVEL_15
,LEVEL_35
- Time ranges. Leaderbords for today / week / month.
DAY_01/31/2022
,WEEK_4/2022
,MONTH_1/2022
- Names scopes. Best in location, clan, race, guild.
LOC_FOREST
,GUILD_NAGIBATORbl
,RACE_ORC
- Events. The best in the event, tournament.
EVENT_HALLOWEEN
,TOURNAMENT_POKER_1871
You are not limited to this list, these are just tags. You can come up with your own approaches to building leaderboard options.
Global leaderboard in its structure repeats a scoped table. It can be accessed by a tag in the format global@key1,key2,key3
, for example global@score
, global@level,exp
Open the leaderboard
In order not to implement the displaying of the leaderboard on your side, you can simply open it in the in-game overlay.
gp.leaderboard.openScoped();
By default, the top is displayed, sorted by player's score, but you can customize everything.
gp.leaderboard.openScoped({
// leaderboard ID
id: 17,
// leaderboard Tag
tag: 'LEVELS',
// Scope name
variant: 'level_15',
// Sort DESC / ASC, by default - leaderboard value
order: 'DESC',
// Number of players on the list, max - 100, by default - leaderboard value
limit: 10,
// Add list of player fields to display in table, in addition to table fields
includeFields: ['rank'],
// Display only required fields one by one
displayFields: ['rank', 'level'],
/**
* Whether to show the current player in the list if he is not in the top
* none — do not show
* first — show first
* last — show last
*/
withMe: 'first'
});
Examples:
// Show leaderboard for the custom level
function openLevelRecords (level) {
gp.leaderboard.openScoped({
tag: 'LEVELS',
variant: `LEVEL_${level}`,
});
}
// Show top players today
gp.leaderboard.openScoped({
tag: 'BEST_DAY',
// 01/31/2022
variant: new Date().toLocaleString('en', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
}),
});
Get the leaderboard
If there is a need to represent the list yourself, then you can simply get a list of players.
const result = await gp.leaderboard.fetchScoped({
// leaderboard ID
id: 17,
// leaderboard Tag
tag: 'LEVELS',
// Scope name
variant: 'level_15',
// Sort DESC / ASC, by default - leaderboard value
order: 'DESC',
// Number of players on the list, max - 100, by default - leaderboard value
limit: 10,
// Add list of player fields to display in table, in addition to table fields
includeFields: ['rank'],
/**
* Whether to show the current player in the list if he is not in the top
* none — do not show
* first — show first
* last — show last
*/
withMe: 'first'
});
// Result
const { leaderboard, players, fields } = result;
Publish player record
In order for the player to see himself in the table, you need to publish his record for the desired version of the table.
The global tables themselves synchronize the player's records after it is saved on the server, there is no need to manually publish the records.
const result = await gp.leaderboard.publishRecord({
// leaderboard ID
id: 17,
// leaderboard Tag
tag: 'LEVELS',
// Scope name
variant: 'level_15',
// Override the highest record?
// By default, the record will be updated if it beats the previous one
override: true,
// Player record, set the values of the required leaderboard fields
record: {
score: myScore,
level: myLevel,
exp: myExp,
},
});
// Result
const { record, fields } = result;
Examples:
// Publish score for the custom level
function saveLevelRecord (level, myScore) {
gp.leaderboard.publishRecord({
tag: 'LEVELS',
variant: `LEVEL_${level}`,
record: {
score: myScore
},
});
}
// Publish today's score
gp.leaderboard.publishRecord({
tag: 'BEST_DAY',
// 01/31/2022
variant: new Date().toLocaleString('en', {
year: 'numeric',
month: '2-digit',
day: '2-digit',
}),
record: {
score: 15781
},
});
Stay in Touch
Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.
GamePush Community Telegram
: @gs_community.
For your suggestions e-mail
: [email protected]
We Wish you Success!