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

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

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.

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!