Добавление GameScore SDK в Godot Engine⁠⁠

// Сразу оговорюсь, что я не такой опытный в написании статей, так что не судите строго.

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

// Примеры, показанные в данной статье не претендуют на звание эталонных. Скорее это даже плохие примеры, но я постараюсь так же объяснить, почему я сделал именно так и почему это плохо.

На тот момент я заканчивал свой проект для Яндекс Игр и, достаточно настрадавшись судьба свела меня с GameScore SDK, которое было призвано решить все мои проблемы.

И так. Для начала давайте разберёмся, что это за зверь-то такой этот ваш ГеймСкор? GameScore - это SDK, которое выступает некоторым агрегатором других SDK. Другими словами "делает всю грязную работу за вас, общаясь со сторонними SDK, предоставляя вам единый список методов, независимый от тех самых SDK". К тому же это позволяет написать код всего один раз и загружать его на все возможные площадки, а GameScore сделает всё остальное.

Ладно. Меньше воды (если смогу), больше дела!
Я не буду здесь расписывать то, как регистрироваться на сайте и как добавлять туда свою игру. Всё это отлично расписано в документации. Наша главная задача - заставить всё это работать в Godot Engine.

Нам понадобится:
1. Проект

2. Шаблон экспорта для Web
3. Фитчи, добавленные в Godot 3.4

4. Шаблон страницы для игры
5. Готовность копаться в JavaScript (хоть и не много)

В первую очередь займемся добавлением загрузки скрипта нашего SDK. Так как наш SDK написан на JavaScript, то и подключать его придётся с помощью добавления строк в наш html файл, который у нас появится после экспорта нашего проекта. Но есть одна проблема - при повторном экспорте наши старания будут перезаписаны. Чтобы этого избежать, мы воспользуемся кастомным шаблоном страницы (я знаю, что можно засунуть в head, однако это не наш случай).

Самый простой способ сделать это:

1. Скачать шаблон страницы с GitHub.
2. Сохранить его в папке проекта.

3. В окне "Project > Export" во вкладке "Options > Html" в параметре "Custom Html Shell" указать наш файл, который мы только что скачали. (если вы предварительно добавили экспорт в HTML5)

Теперь давайте наконец подключим наше SDK!

В первую очередь на нужен код, которым мы будем "активировать" наш SDK. Для этого на сайте SDK идём на страницу нашей игры и почти в самом верху станицы ищем раздел "Install Code". Копируем всё содержимое из тёмного блока!

Теперь открываем наш новоиспеченный файл, который мы скачали и перемещаемся в самый низ данного файла.
Здесь, в предпоследней строке мы видим тег `</body>`. Вставляем скопированный код прямо над ним. Готово. Почти.

Если мы запустим игру, то SDK не будет работать. Всё потому что:
1. Если запускать игру из редактора кнопкой со значком HTML5, то игра запустится на веб сервере, с которым не сможет работать GameScore. Лучше сразу привыкнуть использовать сторонний веб сервер, например на Python, который подымается за 5 секунд в папке с экспортированными файлами проекта и после этого игра будет доступна по адресу `http://localhost:8000`.
2. GameScore будет работать только по тем адресам, которые вы укажете в настройках вашей игры в разделе "Allowed origins". Для теста мы добавим туда наш `http://localhost:8000` и обязательно поставим галочку "Test", чтобы видеть тестовые заглушки вместо настоящей рекламы.

Когда всё готово, наша игра экспортирована, а веб сервер поднят - заходим в браузер и пишем заветный `http://localhost:8000`. Если всё хорошо - в углу экрана вы увидите индикатор загрузки и сообщение "INFO: Devtools Connected". Если всё так - поздравляю, вы подключили GameScore SDK!

Но подождите... А что теперь? SDK есть, а смысла от него нет. Давайте это исправим!
Первым делом разнообразим инициализацию, обратившись к документации. Находим раздел "Инициализация SDK", копируем 3 строчки из середины примера и вставляем в наш шаблон страницы, вместо надписи "// ready", которая находится посреди того кода, что мы вставили ранее.

Должно получиться примерно вот так:

// Тут я пропустил очень важную деталь - забыл заменить `function (gameScore)` на `async (gameScore) =>` (синхронную функцию поменять на асинхронную). Из-за этого чуть не бросил написание статьи.

Теперь, когда мы снова экспортируем игру и запустим её в браузере, мы увидим, что у нас при запуске появляется "реклама". Мы на верном пути! Осталось совсем чуть чуть!!!

Теперь поговорим о том, как же работать с SDK прямо в Godot. Очень просто. В Godot есть класс JavaScript, который, начиная с версии 3.4 (которой я и пользуюсь) позволяет делать очень удобные и приятные вещи такие как:
1. Получать интерфейсы со страницы
2. Создавать JavaScript объекты
3. Обрабатывать коллбеки

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

Приступим. Для начала создадим скрипт GameScore.gd, который сделаем синглтоном с именем GameScore и добавим в него переменную _gs. Это будет наш объект, который мы будем получать с нашей страницы. Для получения объекта со страницы мы можем воспользоваться методом `JavaScript.get_interface("gameSсore")`, который мы добавим в метод _ready(). Однако при попытке запустить нашу игру мы обнаружим три неприятные вещи:

1. Если мы запустим игру не в браузере - редактор выдаст что-то вроде "Класс JavaScript не найден" ничего страшного не произойдёт, но дальше это может создать немало проблем. Класс JavaScript доступен только при экспорте в Web. Чтобы это проверить и обойти, мы воспользуемся проверкой `if OS.has_feature("JavaScript"):`, которая проверит, доступен ли JavaScript.

2. Если мы запускаем игру в браузере - в консоль выпадет ошибка "не найдена переменная gameScore". И это тоже правда. Всё дело в том, что мы не объявляли переменную.

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

Помните мы вставляли в шаблон страницы ещё 3 строчки? Так вот. Прямо над ними мы можем вставить ещё одну строку: `window.gameScore = gameScore;`. Теперь всё будет работать. Но чем же данный способ так плох? Всё дело в том, что записывая наш SDK в глобальную переменную вы буквально даёте возможность любому мамкиному хацкеру недоброжелателю получить достаточно внушительный контроль над методами SDK.

3. Вот вы запускаете игру в браузере, SDK работает, а в переменной _gs красуется изящный null. Как так? А вся проблема в том, что SDK, хоть он и стартует одновременно с движком, однако он может инициализироваться раньше загрузки игры и нашей переменной `window.gameScore` просто ещё не будет существовать. У меня были попытки это обойти максимально изящно, но пока что всё что я делал выглядело как какие-то костыли (и один из них будет ниже).

И наконец, финальный штрих, который просто сложно объяснять, чем один раз показать.
Для удобства демонстрации я постарался не сильно разбивать код на 1000 мелких скриптов.
И так. Сейчас будет куча скриншотов без особого объяснения, потому что это будет код с комментариями.

Но начнем мы со сцены:

Тут буквально мало чего. Я вообще не старался сделать красиво. Главное - понятно.
Принцип прост:
1. При загрузке SDK Label меняет текст внутри себя.
2. При нажатии на Button показывается реклама и после неё увеличивается количество золота.

Теперь по коду. Скрипт, который висит на главной ноде:

А теперь наш синглтон GameScore, который претерпел значительные изменения:

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

И по сути это всё. Если вы посмотрите на код в документации, а потом на меня на то, что было написано в Годо - вы поймёте, что различия не столь большие. Разве что с созданием объектов и коллбеков могут возникнуть некоторые неприятности... Значит пускай это будет для вас бонусом - код который был взят отсюда и подогнан под реалии Годо:

Буду очень признателен, если вы как-то прокомментируете мои потуги. Особенно буду рад советам по улучшению как статьи, так и самого кода. Если всё будет хорошо - планирую сделать целый цикл статей, посвященных Godot в Web. Вот примерный список тех тем, о которых я бы хотел ещё рассказать:
* Кастомизация экрана загрузки
* Динамическая подгрузка ресурсов в Godot
* Лайфхаки и особенности работы HTML5 в Godot

* Документация GameScore SDK. Большинство вопросов и ответов хранится именно тут.
* Что такого произошло в Godot 3.4 и просто "Godot Web progress report #9"
* Репозиторий с данным примером
* Игра, о которой я говорил в самом начале