Изолированная таблица лидеров

info

Разделить рекорды по областям видимости можно с помощью изолированных таблиц лидеров.

Обзор

Изолированные таблицы помогают разделить рекорды по разным областям видимости. Все области видимости хранятся по имени варианта. Имя может быть любым. Несколько примеров использования и примеров тегов для сохранения очков:

Уровни. Свой рейтинг на каждый уровень. LEVEL_15, LEVEL_35
Временные диапазоны. Таблицы лучших игроков за сегодня / неделю / месяц. DAY_01/31/2022, WEEK_4/2022, MONTH_1/2022
Именные разделения. Лучшие в локации, клане, расе, гильдии. LOC_FOREST, GUILD_NAGIBATORbl, RACE_ORC
Эвенты. Лучшие в событии, турнире. EVENT_HALLOWEEN, TOURNAMENT_POKER_1871

tip

Вы не ограничены этим списком, это всего лишь теги. Можно придумать свои подходы к построению вариантов лидербордов.

Глобальная таблица рейтингов по своей структуре повторяет изолированную таблицу. К ней можно получить доступ по тегу в формате global@key1,key2,key3, например global@score, global@level,exp

Открыть таблицу

+1-2 Request

Чтобы не реализовывать на своей стороне отображение таблицы рекордов, её можно просто открыть во внутриигровом оверлее.

JavaScript
Unity

gp.leaderboard.openScoped();

GP_LeaderboardScoped.Open();

По умолчанию выводится топ, отсортированный по очкам игрока, но можно кастомизировать всё.

JavaScript
Unity

gp.leaderboard.openScoped({
    // ID таблицы
    id: 17,
    // Tag таблицы
    tag: 'LEVELS',
    // Название области видимости
    variant: 'level_15',
    // Сортировка DESC / ASC, по умолчанию значение лидерборда
    order: 'DESC',
    // Количество игроков в списке, max - 100, по умолчанию значение лидерборда
    limit: 10,
    // Включить список полей игрока для отображения в таблице, помимо полей таблицы
    includeFields: ['rank'],
    // Вывести только нужные поля по очереди
    displayFields: ['rank', 'level'],
    /**
     * Показывать ли текущего игрока в списке, если он не попал в топ
     * none — не показывать
     * first — показать первым
     * last — показать последним
     */
    withMe: 'first',
    // Показать N ближайших игроков сверху и снизу, максимум 10
    showNearest: 5,
});

GP_LeaderboardScoped.Open(
    // ID или тэг таблицы
    idOrTag = "LEVELS",
    // Название области видимости
    variant = "level_15",
    // Сортировка DESC / ASC, по умолчанию значение лидерборда
    order = "DESC",
    // Количество игроков в списке, max - 100, по умолчанию значение лидерборда
    limit = 10,
    // Показать N ближайших игроков сверху и снизу, максимум 10
    showNearest = 5,
    // Включить список полей игрока для отображения в таблице, помимо полей таблицы
    includeFields = "rank",
    // Вывести только нужные поля по очереди
    displayFields = "rank,level",
    /**
     * Показывать ли текущего игрока в списке, если он не попал в топ
     * none — не показывать
     * first — показать первым
     * last — показать последним
     */
    withMe = "none"
);

Примеры:

// Показать лидерборд для нужного уровня
function openLevelRecords(level) {
    gp.leaderboard.openScoped({
        tag: 'LEVELS',
        variant: `LEVEL_${level}`,
    });
}

// Показать лучших за сегодня
gp.leaderboard.openScoped({
    tag: 'BEST_DAY',
    // 01/31/2022
    variant: new Date().toLocaleString('en', {
        year: 'numeric',
        month: '2-digit',
        day: '2-digit',
    }),
});

Получить таблицу

+1-2 Request

Если есть потребность отрисовывать список самому, то можно просто получить список игроков.

JavaScript
Unity

const result = await gp.leaderboard.fetchScoped({
    // ID таблицы
    id: 17,
    // Tag таблицы
    tag: 'LEVELS',
    // Название области видимости
    variant: 'level_15',
    // Сортировка DESC / ASC, по умолчанию значение лидерборда
    order: 'DESC',
    // Количество игроков в списке, max - 100, по умолчанию значение лидерборда
    limit: 10,
    // Включить список полей игрока для отображения в таблице, помимо полей таблицы
    includeFields: ['rank'],
    /**
     * Показывать ли текущего игрока в списке, если он не попал в топ
     * none — не показывать
     * first — показать первым
     * last — показать последним
     */
    withMe: 'first',
    // Получить N ближайших игроков сверху и снизу, максимум 10
    showNearest: 5,
});

// Результат получения
const { players, fields, topPlayers, abovePlayers, belowPlayers, player } = result;

//Подписка на события
private void OnEnable()
{
    GP_LeaderboardScoped.OnFetchSuccess += OnFetchSuccess;
    GP_LeaderboardScoped.OnFetchError += OnFetchError;
}
//Отписка от событий
private void OnDisable()
{
    GP_LeaderboardScoped.OnFetchSuccess -= OnFetchSuccess;
    GP_LeaderboardScoped.OnFetchError -= OnFetchError;
}

public void Fetch() =>
    GP_LeaderboardScoped.Fetch(
        // ID или тэг таблицы
        idOrTag = "",
        // Название области видимости
        variant = "",
        // Сортировка DESC / ASC, по умолчанию значение лидерборда
        order = "DESC",
        // Количество игроков в списке, max - 100, по умолчанию значение лидерборда
        limit = 10,
        // Показать N ближайших игроков сверху и снизу, максимум 10
        showNearest = 5,
        // Включить список полей игрока для отображения в таблице, помимо полей таблицы
        includeFields = "rank",
        /**
        * Показывать ли текущего игрока в списке, если он не попал в топ
        * none — не показывать
        * first — показать первым
        * last — показать последним
        */
        withMe = "none"
    );

// Результат запроса
private void OnFetchSuccess(string fetchTag, GP_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");

Ответ:

Свойство	Тип	Описание
`players`	LeaderboardPlayer[]	подготовленный к отрисовке топ игроков с учетом моего игрока и игроков перед и после игрока
`topPlayers`	LeaderboardPlayer[]	список лидеров

Если запрос включает withMe: 'first' | 'last' или showNearest: >0, то дополнительно возвращаются поля:

Свойство	Тип	Описание
`player`	LeaderboardPlayer	данные моего игрока с позицией
`abovePlayers`	LeaderboardPlayer[]	список игроков перед моим игроком
`belowPlayers`	LeaderboardPlayer[]	список игроков после моего игрока

Публикация рекорда игрока

+1 Request

Чтобы игрок увидел себя в таблице, нужно опубликовать его рекорд для нужного варианта таблицы.

tip

Глобальные таблицы сами синхронизируют рекорды игрока после его сохранения на сервере, не нужно вручную публиковать рекорды.

JavaScript
Unity

const result = await gp.leaderboard.publishRecord({
    // ID таблицы
    id: 17,
    // Tag таблицы
    tag: 'LEVELS',
    // Название области видимости
    variant: 'level_15',
    // Перезаписать макисмальный рекорд?
    // По-умолчанию рекорд будет обновлен, если он побил предыдущий
    override: true,
    // Рекорд игрока, установите значения нужных полей лидерборда
    record: {
        score: myScore,
        level: myLevel,
        exp: myExp,
    },
});

// Результат публикации
const { record, fields } = result;

//Подписка на события
private void OnEnable()
{
    GP_LeaderboardScoped.OnPublishRecordComplete += OnPublishRecordComplete;
    GP_LeaderboardScoped.OnPublishRecordError += OnPublishRecordError;
}
//Отписка от событий
private void OnDisable()
{
    GP_LeaderboardScoped.OnPublishRecordComplete -= OnPublishRecordComplete;
    GP_LeaderboardScoped.OnPublishRecordError -= OnPublishRecordError;
}

public void PublishRecord() =>
    GP_LeaderboardScoped.PublishRecord(
        // ID или тэг таблицы
        idOrTag = "17",
        // Название области видимости
        variant = "level_15",
        // Перезаписать макисмальный рекорд?
        // По-умолчанию рекорд будет обновлен, если он побил предыдущий
        Override = true,
        // Рекорд игрока, установите значения нужных полей лидерборда
        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");

Примеры:

// Опубликовать очки для нужного уровня
function saveLevelRecord(level, myScore) {
    gp.leaderboard.publishRecord({
        tag: 'LEVELS',
        variant: `LEVEL_${level}`,
        record: {
            score: myScore,
        },
    });
}

// Опубликовать рекорд за сегодня
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,
    },
});

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

Желаем вам успехов!

Изолированная таблица лидеров

Обзор​

Открыть таблицу​

Получить таблицу​

Публикация рекорда игрока​

Оставайтесь на связи​

Обзор

Открыть таблицу

Получить таблицу

Публикация рекорда игрока

Оставайтесь на связи