Механики

Обёртки над атомами: timer, hp-bar, progress, narrative

Механики

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

Отличие от атома:

атом это взаимодействие, которое проверяет ответ (quiz, flashcard);
механика это правила вокруг (время, жизни, прогресс, сюжет).

Отсюда правило из философии: обучение первично, геймификация вторична. Механика ставится тогда, когда служит учебной задаче, а не ради напряжения.

Классы лежат в site/src/mechanics/, полный API в docs/MECHANICS.md. Параметры ниже сверены с layouts/shortcodes/.

timer

Ограничение времени на блок.

{{< with-timer duration="5m" warning="1m" >}}
  {{< quiz question="Какое суждение фактическое?" >}}...{{< /quiz >}}
{{< /with-timer >}}

Параметр	По умолчанию	Описание
`duration`	`5m`	строка вида `30s`, `5m`, `1h`. Не число секунд
`warning`	`1m`	за сколько до конца показать предупреждение, тот же формат
`autoStart`	`true`	стартовать сразу
`position`	`top`	`top`, `bottom`, `floating`
`showControls`	`true`	показывать кнопки управления

События: timer:start, timer:tick с { remaining }, timer:warning, timer:end, timer:pause, timer:resume.

hp-bar

Шкала жизней, ошибка отнимает единицу.

{{< with-hp lives="3" >}}
  {{< quiz question="Вопрос 1" >}}...{{< /quiz >}}
  {{< quiz question="Вопрос 2" >}}...{{< /quiz >}}
{{< /with-hp >}}

Параметр	По умолчанию	Описание
`lives`	`3`	количество жизней
`style`	`hearts`	вид шкалы
`showLabel`	`true`	подпись рядом со шкалой

Логика: на ответ с correct: false отнимает жизнь. На нуле эмитит session:lose, и модуль practice-lose показывает оверлей и блокирует дальнейшие ответы.

События: hp:change с { oldHp, newHp }, hp:zero, session:lose.

progress

Полоса прохождения по уникальным идентификаторам атомов.

{{< with-progress total="5" >}}
  {{< quiz id="q1" >}}...{{< /quiz >}}
  {{< quiz id="q2" >}}...{{< /quiz >}}
{{< /with-progress >}}

Параметр	По умолчанию	Описание
`total`	`10`	сколько элементов считать за сто процентов
`showPercent`	`true`	показывать проценты
`showSteps`	`true`	показывать точки шагов

Логика: считает уникальные id отвеченных атомов. На ста процентах эмитит session:win.

События: progress:update с { current, total, percent }, progress:complete, session:win.

narrative

Сюжетная рамка вокруг атомов.

{{< with-narrative title="Дело о пропавшем дневнике" chapters=`[
  {"id": "scene", "title": "Глава 1: место события", "intro": "Что мы видим, а что додумали."},
  {"id": "versions", "title": "Глава 2: версии", "intro": "Какая догадка выдержит проверку."}
]` >}}
  {{< quiz question="Что здесь наблюдение, а что вывод?" >}}...{{< /quiz >}}
{{< /with-narrative >}}

Параметр	По умолчанию	Описание
`title`	`Story`	название истории
`description`	пусто	подзаголовок
`chapters`	пусто	JSON-массив глав: `id`, `title`, `intro`
`currentChapter`	`0`	с какой главы начать
`showProgress`	`true`	полоса глав
`showChapterNav`	`false`	навигация по главам
`style`	`minimal`	вид оформления

Главы передаются атрибутом chapters в виде JSON, а не YAML внутри блока.

События: narrative:chapter-complete, narrative:complete.

Комбинирование

Механики вкладываются друг в друга:

{{< with-timer duration="5m" >}}
  {{< with-hp lives="3" >}}
    {{< with-progress total="5" >}}
      {{< quiz question="..." >}}...{{< /quiz >}}
    {{< /with-progress >}}
  {{< /with-hp >}}
{{< /with-timer >}}

Каждая механика слушает свои события через EventBus, поэтому атом внутри ни о какой из них не знает.

Поток событий

Ученик отвечает неверно
        |
quiz эмитит { correct: false }
        |
hp-bar слушает и снимает жизнь
        |
hp:change
        |
если жизней ноль -> session:lose -> оверлей practice-lose