@algoritmika/blockly-games v1.0.0

Фронтенд часть онлайн платформы Алгоритмики

отрисовка уровней по заданным в админке конфигам, ui-компоненты, игровые механики

inspired by Blockly Games, based on Google Blockly & Google Closure Library

архитектура JS-приложения

algo — глобальный неймспейс для всего кода платформы

algo.App — основной контроллер приложения

• инициализируется в html

• принимает на вход название механики и конфиг

• содержит всю основную логику работы приложения

• инициализирует все дочерние контроллеры

algo.Ui — контроллер view

• инициализирует ui-компоненты

• содержит логику, связанную с ui: генерация текстов, показ попапа правильного типа и т.д.

algo.ui.Dialog, algo.ui.ErrorBubble, algo.ui.ControlPanel... — ui-компоненты

• наследуются от goog.ui.Component

• содержат подписку на DOM-события типа кликов, ховеров и т.д., в обработчиках событий обычно содержится отправка своих кастомных событий

• не должны содержать никакой логики (должны быть максимально «тупыми»)

algo.games.Maze, algo.games.Turtle, algo.games.Fruits... — игровые механики

• отрисовка карты уровня

• выполнение кода, полученного на основе Blockly

• анимация результата прохождения уровня

• набор отправляемых событий является общим для всех механик и перечислен в файле algo.games.EventType

• также есть два обязательных метода для всех механик: init() и reset() — эти методы дёргаются из algo.App

algo.utils.BlocklyInterface, algo.utils.NightwatchTests, algo.utils.SvgAnimationFallback... — классы для работы с внешними/вспомогательными компонентами системы (сюда же будет перенесён компонент для работы со статистикой — stats-api.js)

• общение между компонентами системы происходит при помощи событий: все компоненты наследуют класс goog.events.EventTarget, экземпляры которого умеют отправлять события и подписываться на них

• исходный код лежит в папке frontend/js/src/, структура директорий повторяет структуру неймспейсов (так же как сделано в самой Google Closure Library)

сборка JS-приложения

• приложение собирается командой npm run build — в папке frontend/

• под капотом происходит вызов питоновского файла frontend/web/js/lib/build-app.py (наследие Blockly Games)

• при сборке JS-код сжимается Google Closure Compiler'ом в режиме "advanced", если сборка прошла без ошибок, то на выходе получается файл frontend/web/js/compressed.js — сжатый код для продакшна и frontend/web/js/uncompressed.js — для разработки (то, какой файл используется сейчас, определяется в файле BlocklyGameAsset.php, в зависимости от переменной YII_DEBUG, которая true для dev-окружения)

CSS

• структура директорий со стилями (frontend/web/css) и картинками (frontend/web/img) также примерно повторяет структуру неймспейсов JS, например: стили для ui-компонента algo.ui.Dialog будут лежать в папке frontend/web/css/ui/dialog.css

• сборка CSS в данный момент отсутствует (каждый файл грузится отдельным запросом)

• желательно соблюдать правило «один файл — один ui-компонент»

• слова в названиях css-классов разделяются дефисами

HTML

• весь html сейчас лежит в php-файлах, в том числе перечень команд для данного уровня (см. toolbox)

• в данный момент на каждую механику создаётся свой отдельный php-файл в папке frontend/views/lesson, но их отличия минимальны и в будущем файл будет один на все механики

Как добавить новую механику

1. Создать php-файл для инициализации общего лэйаута механики и прокидывания конфига уровня из админки в js: frontend/views/lesson/new-mechanics.php (за основу можно взять frontend/views/lesson/maze.php).
2. Прописать в этот файл название механики, добавить поля в конфиг уровня (если требуется), отредактировать список нужных команд Блокли (см. toolbox).
3. Создать js-файлы c механикой и описанием поведения команд Блокли: frontend/web/js/src/algo/games/new-mechanics/new-mechanics.js, frontend/web/js/src/algo/games/new-mechanics/blocks.js.
4. Добавить знание о новой механике в основной файл приложения frontend/web/js/src/algo/app.js.
5. Добавить знание о новой механике в common/config/params.php.
6. Создать новый уровень в админке (http://backoffice.algoritmika.org/admin/level). Лучше взять за основу какой-нибудь существующий и скопировать по id. Указать в конфиге уровня в поле template название php-файла из папки frontend/views/lesson.
7. Сохранить и нажать «Проверить уровень» (или «Решение уровня»).