# Пример: Runtime integration (§31-6)

Готовый вертикальный срез «игра целиком» на чистом `$`: RmlUi HUD, локализация
на ходу, вставка на `$.timeline`, музыкальные слои через `$.audio` и переход
между комнатами через область владения `$.scene` (§5). Относится к разделу §31
«Документация и вертикальные примеры» и последовательности §49
[спецификации производственной готовности](https://github.com/Nikide/russiano2d/blob/main/docs/PRODUCTION_READINESS.md).

Пошаговый разбор — [docs/tutorial-runtime-integration.md](tutorial-runtime-integration).

## Запуск

```bash
./build/russiano2d --game demos/showcase
python3 tools/run_tests.py showcase_test                              # автоматическая приёмка
R2D_BINARY=build-2d/russiano2d python3 tools/run_tests.py showcase_test
```

Управление (демо живёт само, клавиши — для ручной проверки):
`H` — ru/en, `1`/`2` — громкость слоёв музыки, `T` — вставка, `Enter` — арена,
`Esc` — отменить подготовку.

## Что показывает

| Слой | Как | Проверка |
|---|---|---|
| RmlUi HUD | `$.ui.doc('demos/showcase/rml/hud.rml')` + `doc.text(el, $.tr(...))` в одном `$.update` | HUD показывает очки игры и меняет их из маркера вставки |
| Persistent HUD | документ RmlUi живёт вне сцен и областей | HUD виден после вставки и перехода комнаты |
| Локализация | `$.i18n.add/lang` + `$.tr`, реплики — ключи словаря | `setLang('en')` меняет строки HUD и текст диалога без перезапуска |
| Вставка | `$.timeline.define` + `auto` + `stop` | доходит до конца (`reason: 'end'`), прерывается (`reason: 'manual'`) |
| Маркеры вставки | `emit` и `do` в битах | маркер сработал один раз, очки выросли на 5 |
| Музыкальные слои | `$.audio.bus('music.*')` + `$.audio.play(..., { bus })` | три шины, громкость каждой меняется отдельно |
| Scoped transition | `$.scene.prepare('arena')` → `commit` / `discard` | commit заменяет мир, discard не публикует (число узлов до/после) |

## Файлы

| Файл | Что |
|---|---|
| `main.js` | точка входа проекта; стартовая комната в области владения |
| `index.js` | i18n, HUD, комнаты, timeline-вставка, слои музыки, фасад `$.showcase` |
| `rml/hud.rml`, `rml/hud.rcss` | разметка и стили HUD |
| `project.json` | имя окна и размер |

## Чего не хватило в API (честно)

1. **§25 (music stems) не реализован.** У звука нет общего transport/clock:
   нельзя запустить stem'ы с одной временной метки, перемотать их вместе или
   гарантировать sample-accurate синхронность. В примере слои стартуют в одном
   кадре на общих шинах `music.*`, а «интенсивность» — это громкость шины.
2. **У RmlUi-документов нет data-binding** на `$.store`/`$.i18n`: строки HUD
   приходится переписывать кадровым хуком (`doc.text(el, $.tr(...))`).
   Локализация «на лету» поэтому работает через `$.tr`, а не через разметку.
3. **`$.scene.prepare` не скрывает staging-мир.** Узлы временной области
   физически существуют в мире до `commit` (в примере — один кадр). Прогресс
   загрузки и «невидимая» подготовка — задача §45.
4. **Вставка `$.timeline` — не overlay.** Таймлайн регистрирует сцену на своё
   имя и грузится обычным `$.scene.load`, поэтому мир комнаты на время вставки
   снимается и собирается заново после неё. Persistent HUD (документ RmlUi) при
   этом не страдает.
5. Демо-лаунчер (`demos/launcher.js`) содержит статический список `DEMOS` и в
   этом примере не менялся: запуск — `--game demos/showcase`.