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.

JavaScript

ss.leaderboard.openScoped();

Unity

SS_LeaderboardScoped.Open();

By default, the top is displayed, sorted by player's score, but you can customize everything.

JavaScript

ss.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
});

Unity

SS_LeaderboardScoped.Open(
    // leaderboard ID or Tag
    idOrTag = "LEVELS",
     // Scope name
    variant = "level_15",
    // Sorting by fields from left to right
    orderBy = "score",
    // DESC sorting – big values first, ASC sorting – small values first
    order = "DESC",
    // The number of players in the list
    limit = 10,
    // Show N nearest players above and below, maximum 10
    showNearest = 5,

    /// Include the field list to display in the leaderboard, in addition to orderBy
    includeFields = "rank",
    /// Display only the 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 = "none"
);

Examples:

// Show leaderboard for the custom level
function openLevelRecords(level) {
    ss.leaderboard.openScoped({
        tag: 'LEVELS',
        variant: `LEVEL_${level}`
    });
}

// Show top players today
ss.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.

JavaScript

const result = await ss.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;

Unity

//Subscribe to events
private void OnEnable()
{
    SS_LeaderboardScoped.OnFetchSuccess += OnFetchSuccess;
    SS_LeaderboardScoped.OnFetchError += OnFetchError;
}
//Unsubscribe from events
private void OnDisable()
{
    SS_LeaderboardScoped.OnFetchSuccess -= OnFetchSuccess;
    SS_LeaderboardScoped.OnFetchError -= OnFetchError;
}

public void Fetch() =>
    SS_LeaderboardScoped.Fetch(
        // leaderboard ID or Tag
        idOrTag = "17",
        // Scope name
        variant = "level_15",
        // Sorting by fields from left to right
        orderBy = "score",
        // DESC sorting – big values first, ASC sorting – small values first
        order = "DESC",
        // The number of players in the list
        limit = 10,
        // Show N nearest players above and below, maximum 10
        showNearest = 5,
        /// Include the field list to display in the leaderboard, in addition to orderBy
        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 = "none"
    );

// Result
private void OnFetchSuccess(string fetchTag, SS_Data data)
{
    var players = data.GetList<LeaderboardScopedFetchData>();

    Debug.Log("FETCH TAG: " + fetchTag);

    for (int i = 0; i < players.Count; i++)
    {
        Debug.Log("PLAYER: AVATAR: " + players[i].avatar);
        Debug.Log("PLAYER: ID: " + players[i].id);
        Debug.Log("PLAYER: SCORE: " + players[i].score);
        Debug.Log("PLAYER: NAME: " + players[i].name);
        Debug.Log("PLAYER: POSITION: " + players[i].position);
        Debug.Log("PLAYER: LEVEL: " + players[i].level);
    }
}

private void OnFetchError() => Debug.Log("LEADERBOARD SCOPED: ON FETCH: ERROR");

Response:

Property	Type	Description
players	LeaderboardPlayer[]	prepared for rendering top players considering my player and players above and below my player
topPlayers	LeaderboardPlayer[]	list of leaders

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

Property	Type	Description
player	LeaderboardPlayer	data of my player with position
abovePlayers	LeaderboardPlayer[]	list of players above my player
belowPlayers	LeaderboardPlayer[]	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.

JavaScript

const result = await ss.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;

Unity

//Subscribe to events
private void OnEnable()
{
    SS_LeaderboardScoped.OnPublishRecordComplete += OnPublishRecordComplete;
    SS_LeaderboardScoped.OnPublishRecordError += OnPublishRecordError;
}
//Unsubscribe from events
private void OnDisable()
{
    SS_LeaderboardScoped.OnPublishRecordComplete -= OnPublishRecordComplete;
    SS_LeaderboardScoped.OnPublishRecordError -= OnPublishRecordError;
}

public void PublishRecord() =>
    SS_LeaderboardScoped.PublishRecord(
        // leaderboard ID or Tag
        idOrTag = "17",
        // 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
        key1 = "key1",
        value1 = 1,
        key2 = "key2",
        value2 = 2,
        key3 = "key3",
        value3 = 3
    );

private void OnPublishRecordComplete() => Debug.Log("LEADERBOARD SCOPED: ON PUBLISH RECORD: COMPLETE");
private void OnPublishRecordError() => Debug.Log("LEADERBOARD SCOPED: ON PUBLISH RECORD: ERROR");

Examples:

// Publish score for the custom level
function saveLevelRecord(level, myScore) {
    ss.leaderboard.publishRecord({
        tag: 'LEVELS',
        variant: `LEVEL_${level}`,
        record: {
            score: myScore
        }
    });
}

// Publish today's score
ss.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.

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!