Плагин VK Bridge C3 (подключение турнирной таблицы)

Одной из удобных возможностей плагина VK Bridge для Construct 3 является поддержка турнирных таблиц (также называемых таблицами рекордов или лидербордами).

С помощью данного плагина можно добавить такую таблицу в Вашу игру, а сами рекорды будут храниться в профилях игроков и автоматически сортироваться по их достижениям: по набранным очкам или по пройденным уровням.

Давайте посмотрим, как это работает на примере игры Шароматика (или по-буржуйски: Balls-nums).

Будем считать, что Вы уже интегрировали плагин VK Bridge в свою игру. Если нет — посмотрите, как это делается в нашей предыдущей статье.

1. Настройка в панели Вконтакте

Для начала включим поддержку эту турнирных таблиц в настройках Вашей игры в панели Вконтакте:

В профиле разработчика заходим в раздел Мои приложения, заходим в меню Редактирование Вашей игры. Выбираем раздел Информация и находим параметр: Тип турнирной таблицы.

Здесь выбираем, будет ли наша турнирная таблица сортировать игроков по набранным очкам или же по пройденным уровням. В Шароматике уровней как таковых нет, поэтому остаётся только вариант По очкам.

В данной панели больше ничего не требуется, переходим непосредственно к событиям в Construct 3.

2. Запись рекорда игрока

Важно! Запись рекордов в таблицу начнёт работать только после того, как Ваша игра будет одобрена модератором Вконтакте. Поэтому, если игра ещё не одобрена, имеет смысл дождаться одобрения, а уже потом добавлять турнирную таблицу в игру. Иначе не будет возможности её полностью протестировать.

Сама запись рекорда с помощью плагина делается очень просто и одинаково для любой платформы. Её можно вынести в отдельную функцию и запускать из любого места игры в удобный момент.

Здесь score — это переменная с количеством очков из игры. А activity: Scrore — переключатель: ScoreLevel, с помощью которого мы показываем плагину, какой именно тип рекорда мы передаём для записи.

Плагин VK Bridge отслеживает, была ли запись рекорда удачной или нет.

Неудачной она считается в двух случаях:

  • если рекорд не смог быть записан (например, если игра ещё не одобрена модератором),
  • если новый рекорд меньше уже записанного для данного игрока.

В противном случае рекорд обновляется.

По окончании успешной или неудачной записи рекорда, мы можем выполнить какие-то действия, например, вывести турнирную таблицу. В данном случае этот вывод таблицы я тоже вынес в отдельную функцию.

3. Вывод турнирной таблицы для разных платформ

Вконтакте по-разному выводит турнирные таблицы в мобильном приложении Вконтакте и в веб-версии сайта vk,com в браузере. Поэтому для них используются разные команды плагина.

Здесь используется наша собственная переменная client для определения текущей платформы (мобильное приложение или веб-браузер), Об этом можно почитать в статье про интеграцию рекламы ВК с помощью данного плагина.

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

Для веб-браузера мы выбираем переключателем Type между Score и Levels и задаём дополнительные поля через запятую, из тех что могут понадобиться, согласно их списку объектов, указанных в руководстве от ВК. Базовые поля можно не указывать, они будут возвращены по умолчанию.

В данном случае, я задал дополнительное поле photo_100, возвращающее аватарки игроков размером 100 на 100 пикселей.

И для обоих случаев указываем режим mode: будут ли выведены все существующие игроки (All users) или только друзья данного игрока (Friends).

Лайфхак: Если примитивный мобильный вариант Вас не устраивает, можно для мобильного приложения тоже сделать в виде веб-варианта — он тоже будет работать.

4. Вывод турнирной таблицы игры в мобильном приложении Вконтакте

В мобильном приложении турнирная таблица появится без лишних телодвижений в стандартном виде.

Игрок увидит что-то вроде этого:

4. Вывод турнирной таблицы игры в Веб-браузере

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

Для начала, подсчитаем количество игроков в присланном списке. И если сохранённые рекорды найдены, то включаем панель нашего лидерборда — как обычно — запуском отдельной функции.

В противном случае нет смысла выводить таблицу — переходим сразу к экрану окончания игры.

Сама функция вывода турнирной таблицы в моём случае выглядит примерно так:

Это верхняя часть события (что поместилось в экран). Здесь видно, что мы включаем фон и отключаем ненужные кнопки, которые могут случайно сработать из-под лидерборда. Причём, сам лидерборд можно запускать и отдельно — со стартового экрана — по специальной кнопке. На этот случай добавлено условие, определяющее, что это за экран и выключающее соответствующие кнопки.

Во второй части этой функции мы перебираем полученные данные и раскидываем их по таблице:

  • имя и фамилию игроков,
  • аватарки игроков,
  • заработанные ими очки.

Важный момент: Сейчас ВК возвращает список максимум из 20 рекордов. То есть, делать таблицу более чем на 20 позиций нет смысла.

В моём случае таблица рассчитана на 10 рекордов. Если игроков пока меньше 10, то согласно условию будут показаны только те, что есть (чтобы не было стрёмных текстов с нулями вместо имён).

Здесь аватарки сделаны кнопками, чтобы по ним можно было перейти в профили игроков. Для этого в каждую кнопку записываем ID игрока и при нажатии на неё подставляем этот ID в ссылку, которую затем открываем в браузере.

Стоит отметить, что аватарки изначально приходят квадратными, поэтому я наложил на них сверху дополнительные спрайты с круглой дыркой (маску). При достаточной фантазии, можно сделать посимпатичнее, как в игре Китайские фонарики (кнопка лидерборда слева-снизу)

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

Таким образом, в функции показа лидерборда у нас:

  1. Проверяется количество присланных рекордов и с помощью специального условия в панели включится ровно столько текстов рекордов, сколько было прислано, но не более 10 (больше не влезает в мою фиксированную таблицу, но при желании и умении можно прикрутить прокрутку списка 😉
  2. В цикле перебираем присланные имена игроков и их рекорды и выводим их в соответствующие текстовые блоки и картинки.
  3. И когда всё это выполнено, переносим заполненный лидерборд на экран и включаем его плавное проявление.

Стоит также предусмотреть случай, когда таблица по каким-то причинам не выведена. Тогда просто показываем игроку окно конца уровня.

5. Ключи для вывода данных лидерборда в веб-браузере

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

Чтобы работать с ними предусмотрены 3 команды плагина, которые мы встречали на скриншотах выше:

  • VKBridge.BoardCount — количество рекордов (сколько разных игроков сохраняли свои рекорды),
  • VKBridge.BoardData — данные о рекорде конкретного игрока: количество строк в таблице (ключ: count) id аккаунта игрока (ключ: user_id), достигнутый уровень (ключ: level — для таблицы по уровням) или набранное количество очков (ключ: score — для таблицы по очкам).
  • VKBridge.BoardProf — данные о самом игроке (о его профиле): id его аккаунта (ключ: id), Имя (ключ: first_name), Фамилия (ключ: last_name) и т.д.

Доступ к массивам BoardData и BoardProf идёт по индексу игроков в таблице рекордов, начиная с нуля: 0-е место, 1-е место, 2-е место и т.д.).

Полный список полей в массивах можно посмотреть здесь: https://vk.com/dev/objects/user

Для справки, вот как может выглядеть ответ сервера:

Для турнирной таблицы по пройденным уровням:

BoardData: — данные рекордов

«response»: {
«count»: 1,
«items»: [{
«user_id»: 818250,
«level»: 6
}],

BoardProf: — данные игроков

«profiles»: [{
«first_name»: «Миша»,
«id»: 818250,
«last_name»: «Андриевский»,
«can_access_closed»: false,
«is_closed»: true

Для турнирной таблицы по набранным очкам:

BoardData:

«response»: {
«count»: 1,
«items»: [{
«user_id»: 818250,
«score»: 225
}],

BoardProf:

«profiles»: [{
«first_name»: «Миша»,
«id»: 818250,
«last_name»: «Андриевский»,
«can_access_closed»: false,
«is_closed»: true