Skip to main content

Scoped Leaderboard

info

To separate records by visibility areas, you can use scoped leaderboards tables.

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
tip

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

+1-2 Request

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',
// Show N nearest players above and below, maximum 10
showNearest: 5,
});

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

+1-2 Request

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',
// Get N nearest players above and below, maximum 10
showNearest: 5,
});

// Result
const { players, fields, topPlayers, abovePlayers, belowPlayers, player } = result;

Response:

PropertyTypeDescription
playersLeaderboardPlayer[]prepared for rendering top players considering my player and players above and below my player
topPlayersLeaderboardPlayer[]list of leaders

If the request includes withMe: 'first' or 'last' or showNearest: >0, the following additional fields are returned:

PropertyTypeDescription
playerLeaderboardPlayerdata of my player with position
abovePlayersLeaderboardPlayer[]list of players above my player
belowPlayersLeaderboardPlayer[]list of players below my player

Publish player record

+1 Request

In order for the player to see himself in the table, you need to publish his record for the desired version of the table.

tip

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!