@vnejs/docs 0.2.1

package/scenario.catalog/stubs/scenario.md

@@ -0,0 +1,17 @@
+# $ scenario
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ scenario <action> …` |
+| Actions / args | anchor, goto |
+| Plugin doc | [core/scenario.md](../plugins/core/scenario.md) |
+
+## Примеры
+
+```vne
+$ scenario anchor loop_start
+$ scenario goto loop_start
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/settings.defaults.md

@@ -0,0 +1,16 @@
+# $ settings.defaults
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ settings.defaults` |
+| Actions / args | — |
+| Plugin doc | [views.screens/settings.defaults.md](../plugins/views.screens/settings.defaults.md) |
+
+## Примеры
+
+```vne
+$ settings.defaults
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/stack.md

@@ -0,0 +1,18 @@
+# $ stack
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ stack <action> …` |
+| Actions / args | jump, call, pop |
+| Plugin doc | [core/stack.md](../plugins/core/stack.md) |
+
+## Примеры
+
+```vne
+$ stack jump prologue/3
+$ stack call sub
+$ stack pop
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/text.meet.md

@@ -0,0 +1,16 @@
+# $ text.meet
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ text.meet <speaker>` |
+| Actions / args | — |
+| Plugin doc | [text/meet.md](../plugins/text/meet.md) |
+
+## Примеры
+
+```vne
+$ text.meet fl
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/text.wall.md

@@ -0,0 +1,17 @@
+# $ text.wall
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ text.wall <action>` |
+| Actions / args | clear, start, end |
+| Plugin doc | [text/wall.md](../plugins/text/wall.md) |
+
+## Примеры
+
+```vne
+$ text.wall start
+$ text.wall end
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/time.md

@@ -0,0 +1,17 @@
+# $ time
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ time <action> …` |
+| Actions / args | add, set |
+| Plugin doc | [time/time.md](../plugins/time/time.md) |
+
+## Примеры
+
+```vne
+$ time set …
+$ time add …
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.animation.md

@@ -0,0 +1,18 @@
+# $ ul.animation
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.animation <action> …` |
+| Actions / args | set, unset |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.animation set …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.bg.md

@@ -0,0 +1,18 @@
+# $ ul.bg
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.bg <action> …` |
+| Actions / args | show, hide, change |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.bg show …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.clip.md

@@ -0,0 +1,18 @@
+# $ ul.clip
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.clip <action> …` |
+| Actions / args | set, unset |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.clip set …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.fill.md

@@ -0,0 +1,18 @@
+# $ ul.fill
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.fill <action> …` |
+| Actions / args | show, change, hide |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.fill show …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.filter.md

@@ -0,0 +1,18 @@
+# $ ul.filter
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.filter <action> …` |
+| Actions / args | set, unset |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.filter set …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.mask.md

@@ -0,0 +1,18 @@
+# $ ul.mask
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.mask <action> …` |
+| Actions / args | set, unset, change |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.mask set …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.scale.md

@@ -0,0 +1,18 @@
+# $ ul.scale
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.scale <action> …` |
+| Actions / args | set, unset |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.scale set …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.sprite.md

@@ -0,0 +1,18 @@
+# $ ul.sprite
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.sprite <action> …` |
+| Actions / args | show, hide, change, move |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.sprite show …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/ul.text.md

@@ -0,0 +1,18 @@
+# $ ul.text
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ ul.text <action> …` |
+| Actions / args | show, hide, change, move |
+| Plugin doc | [canvas.layers/ul.md](../plugins/canvas.layers/ul.md) |
+
+## Примеры
+
+```vne
+$ ul.text show …
+```
+
+Паттерн всех слоёв одинаков — см. [guide canvas](../../scenario.guide/canvas.md).
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/video.md

@@ -0,0 +1,16 @@
+# $ video
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ video play …` |
+| Actions / args | play |
+| Plugin doc | [views/video.md](../plugins/views/video.md) |
+
+## Примеры
+
+```vne
+$ video play {cutscene/01}
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.catalog/stubs/wallet.md

@@ -0,0 +1,17 @@
+# $ wallet
+
+| | |
+|--|--|
+| Тип | `module` (`$`) |
+| Сигнатура | `$ wallet <action> …` |
+| Actions / args | add, set, reset |
+| Plugin doc | [entities/wallet.md](../plugins/entities/wallet.md) |
+
+## Примеры
+
+```vne
+$ wallet add …
+$ wallet reset
+```
+
+Source of truth: `SCENARIO_COMMANDS` в соответствующем `contracts/**/commands.ts`.

package/scenario.guide/README.md

@@ -0,0 +1,82 @@
+# Сценарный гайд (вариант B)
+
+Авторский слой для написания `.vne`. Здесь — синтаксис, примеры и типичные паттерны. События и модули плагинов — в [`../plugins/`](../plugins/).
+
+Параллельный вход: [`../scenario.catalog/`](../scenario.catalog/) (индекс команд из `SCENARIO_COMMANDS`).
+
+## Оглавление
+
+| Страница | Тема |
+|----------|------|
+| [dialogue.md](./dialogue.md) | Реплики, speakers, wall / meet |
+| [flow.md](./flow.md) | `stack`, `scenario`, `pause`, `save` |
+| [vars.md](./vars.md) | `flag`, `counter` |
+| [choose.md](./choose.md) | `% choose` |
+| [point-and-click.md](./point-and-click.md) | `% point-and-click` |
+| [qte-random.md](./qte-random.md) | `% qte`, `% random` |
+| [audio.md](./audio.md) | `$ audio.*` |
+| [canvas.md](./canvas.md) | слои `bl` / `fl` / `ml` / `ul` |
+| [views.md](./views.md) | interface, screens, video, comment, achievement |
+
+## Структура файла
+
+```vne
+import tests/stack
+
+label init:
+  "Стартовая реплика"
+  $ stack jump prologue/1
+
+label prologue/1:
+  fl "Реплика персонажа"
+```
+
+- **`import <path>`** — подключить другой `.vne` (путь без расширения, относительно каталога scenario).
+- **`label <name>:`** — метка; к ней прыгают через `$ stack jump/call` и `$ scenario goto`.
+- Отступы (indent) задают тело блоков (`% choose`, `% flag`, …).
+
+## Типы строк
+
+| Вид | Пример | Смысл |
+|-----|--------|--------|
+| Диалог | `"Текст"` или `fl "Текст"` | Модуль `other` (без `$`) |
+| Модуль | `$ flag seen` | Префикс `$` — вызов модуля |
+| Блок | `% choose` | Префикс `%` — блок с indent-телом |
+
+## Keywords строки
+
+После `|` на той же строке (общие для сценария):
+
+| Keyword | Смысл |
+|---------|--------|
+| `async` | Не блокировать продвижение, пока строка выполняется |
+| `autonext` | Автопереход дальше после строки |
+| `skip-if-possible` | Пропустить строку, если движок может |
+
+Доменные keywords живут в плагинах, например `| global` (vars), `| qte-fallback` (choose↔qte), `| extend` (text).
+
+## Props в indent
+
+Под блоками и опциями часто встречаются свойства:
+
+```vne
+% choose.option "Осмотреть"
+  hided: $ flag seen
+  disabled: $ counter n > 3
+  qte: easy
+```
+
+- **`hided:`** — скрыть опцию, если условие истинно.
+- **`disabled:`** — показать, но недоступна.
+- Условие — обычно `$ flag …` / `$ counter …` (иногда с `| global`).
+
+## Комментарии
+
+```vne
+# комментарий
+// тоже комментарий
+```
+
+## Дальше
+
+Начните с [dialogue.md](./dialogue.md) и [flow.md](./flow.md), затем ветвления ([choose.md](./choose.md)) и медиа ([canvas.md](./canvas.md), [audio.md](./audio.md)).

package/scenario.guide/audio.md

@@ -0,0 +1,29 @@
+# Аудио: $ audio.*
+
+Четыре канала с одинаковым набором действий:
+
+| Модуль | Назначение |
+|--------|------------|
+| `$ audio.music` | Музыка / BGM |
+| `$ audio.ambient` | Амбиент |
+| `$ audio.sound` | SFX |
+| `$ audio.voice` | Голос |
+
+## Действия
+
+`play`, `stop`, `pause`, `resume`, `volume`
+
+```vne
+$ audio.music play {theme/hospital}
+$ audio.ambient play {rain}
+$ audio.sound play {ui/click}
+$ audio.voice play {fl/line_01}
+$ audio.music volume 0.5
+$ audio.music stop
+```
+
+Точные аргументы после `play` (id трека, fade и т.д.) зависят от контента и контракта audio; смотрите примеры в `games/*/game/**/scenario/`.
+
+## См. также
+
+- [`../plugins/audio/music.md`](../plugins/audio/music.md), [`ambient.md`](../plugins/audio/ambient.md), [`sound.md`](../plugins/audio/sound.md), [`voice.md`](../plugins/audio/voice.md)

package/scenario.guide/canvas.md

@@ -0,0 +1,46 @@
+# Canvas-слои: bl / fl / ml / ul
+
+Команды вида `$ <layer>.<kind> <action> …`.
+
+## Слои
+
+| Префикс | Обычный смысл |
+|---------|----------------|
+| `bl` | Back layer (фон, дальние объекты) |
+| `ml` | Middle |
+| `fl` | Front / персонажи часто здесь |
+| `ul` | UI / верхний слой |
+
+Состав `kind` зависит от слоя (например у `ul` может не быть `video`). Типичные kind:
+
+| Kind | Действия (часто) |
+|------|------------------|
+| `bg` | `show`, `hide`, `change` |
+| `sprite` | `show`, `hide`, `change`, `move` |
+| `video` | `show`, `hide`, `change` |
+| `text` | `show`, `hide`, `change`, `move` |
+| `fill` | `show`, `change`, `hide` |
+| `filter` / `scale` / `clip` / `mask` / `animation` | `set` / `unset` (у mask ещё `change`) |
+
+## Примеры
+
+```vne
+$ bl.bg show {castle/hospital_room}
+$ bl.bg change {castle/surgery_room/index} 300
+$ fl.sprite show {fl} center
+$ ul.sprite show {lupa} …
+$ bl.fill show …
+$ bl.filter set …
+$ bl.scale set …
+$ bl.mask set …
+$ bl.animation set …
+```
+
+Число после bg/sprite часто — длительность перехода (мс). Id медиа в `{…}`.
+
+Не копируйте документацию на каждый слой: паттерн один — меняется только префикс `bl` / `fl` / `ml` / `ul`.
+
+## См. также
+
+- Слои: [`../plugins/canvas.layers/bl.md`](../plugins/canvas.layers/bl.md), [`fl.md`](../plugins/canvas.layers/fl.md), [`ml.md`](../plugins/canvas.layers/ml.md), [`ul.md`](../plugins/canvas.layers/ul.md)
+- Kind: [`../plugins/canvas/bg.md`](../plugins/canvas/bg.md), [`sprite.md`](../plugins/canvas/sprite.md), …

package/scenario.guide/choose.md

@@ -0,0 +1,54 @@
+# Выбор: % choose
+
+Меню опций. UI рисует view-плагин; логика веток — здесь.
+
+```vne
+% choose
+  % choose.option "Осмотреть"
+    hided: $ flag seen
+    $ flag seen
+    "Осмотрели."
+    $ choose repeat
+  % choose.option "Уйти"
+    "Уходим."
+# дальше — когда repeat больше не нужен / все option скрыты
+```
+
+## Команды
+
+| Синтаксис | Смысл |
+|-----------|--------|
+| `% choose` | Открыть выбор; собрать `% choose.option` |
+| `% choose.option "…"` | Ветка; невыбранные пропускаются по indent |
+| `$ choose repeat` | Вернуться к ближайшему `% choose` **выше** в той же метке |
+
+Если все опции `hided` (или список пуст) — блок пропускается.
+
+## Props и keywords опции
+
+```vne
+% choose
+  % choose.option "С QTE"
+    qte: easy
+    "Успех — эта ветка"
+  % choose.option "Fallback" | qte-fallback
+    "Прямой выбор или fail QTE"
+  % choose.option "Скрытая"
+    hided: $ flag done
+  % choose.option "Недоступная"
+    disabled: $ flag locked
+```
+
+- **`hided:`** / **`disabled:`** — условия видимости/доступности.
+- **`qte: <id>`** — перед входом в ветку запустить QTE (нужен compatibility choose↔qte в бандле).
+- **`| qte-fallback`** — ветка при провале QTE.
+
+## Цикл «осмотреть → меню»
+
+Паттерн: в каждой опции осмотра ставить флаг и `$ choose repeat`; когда всё осмотрено (`hided`), choose сам уйдёт дальше.
+
+## См. также
+
+- [`../plugins/scenario/choose.md`](../plugins/scenario/choose.md)
+- View: [`../plugins/views.scenario/choose.md`](../plugins/views.scenario/choose.md)
+- QTE: [qte-random.md](./qte-random.md)

package/scenario.guide/dialogue.md

@@ -0,0 +1,58 @@
+# Диалог и текст
+
+Строки без `$` / `%` — реплики (модуль `other`, плагин text).
+
+## Базовый диалог
+
+```vne
+"Наррация от третьего лица."
+fl "Реплика персонажа с id fl."
+co "Реплика Коралины."
+```
+
+- Строка в кавычках без speaker id — наррация / «other».
+- `<speaker> "…"` — реплика с именем спикера (id из конфига игры).
+
+## Postfix и inject
+
+```vne
+fl "Мне всегда нравилось твоё имя."
+  postfix: nod
+
+% choose.option "А сейчас счетчик равен testsCounter"
+  inject:
+    $ counter testsCounter
+```
+
+- **`postfix:`** — доп. токен к реплике (жесты, вариации — зависит от бандла/контента).
+- **`inject:`** — подставить значение в текст опции/строки через exec.
+
+## text.meet
+
+Зафиксировать «знакомство» со спикером (имя в UI и т.п.):
+
+```vne
+$ text.meet fl
+fl "Нога заживёт."
+```
+
+Сигнатура: `$ text.meet <speakerId>`.
+
+## text.wall
+
+Стена текста (многострочный блок на экране):
+
+```vne
+$ text.wall start
+"Первый абзац"
+"Второй абзац"
+$ text.wall end
+$ text.wall clear
+```
+
+Действия: `start`, `end`, `clear`.
+
+## См. также
+
+- Плагины: [`../plugins/text/text.md`](../plugins/text/text.md), [`meet.md`](../plugins/text/meet.md), [`wall.md`](../plugins/text/wall.md)
+- Каталог: [`../scenario.catalog/stubs/other.md`](../scenario.catalog/stubs/other.md)

package/scenario.guide/flow.md

@@ -0,0 +1,71 @@
+# Поток сценария: stack, scenario, pause, save
+
+## stack — переходы по меткам
+
+```vne
+$ stack jump prologue/3
+$ stack call testsStackSubroutine
+$ stack pop
+```
+
+| Действие | Смысл |
+|----------|--------|
+| `jump <label>` | Перейти на метку **без** сохранения возврата |
+| `call <label>` | Push текущей позиции, затем переход; в конце метки обычно `pop` или auto-pop |
+| `pop` | Вернуться к сохранённой позиции |
+
+`call` может передавать аргументы (см. тесты `tests/stack` в играх).
+
+## scenario — якоря внутри метки
+
+```vne
+$ scenario anchor loop_start
+"…"
+$ scenario goto loop_start
+```
+
+| Действие | Смысл |
+|----------|--------|
+| `anchor <name>` | Именованная точка в текущей метке |
+| `goto <name>` | Перейти к якорю (в той же метке) |
+
+## pause
+
+```vne
+$ pause
+```
+
+Пауза сценария (ожидание игрока / логика плагина pause).
+
+## save
+
+```vne
+$ save key "Глава: «Пробуждение в кошмаре»"
+$ save.auto
+```
+
+| Команда | Смысл |
+|---------|--------|
+| `$ save key "…"` | Задать ключ/подпись слота сохранения |
+| `$ save.auto` | Автосохранение |
+
+## Типичный каркас
+
+```vne
+label init:
+  $ stack jump newGame
+
+label newGame:
+  $ bl.bg show {castle/hospital_room}
+  $ stack jump prologue/1
+
+label prologue/1:
+  "…"
+  $ stack jump prologue/2
+```
+
+## См. также
+
+- [`../plugins/core/stack.md`](../plugins/core/stack.md), [`scenario.md`](../plugins/core/scenario.md)
+- [`../plugins/scenario/pause.md`](../plugins/scenario/pause.md)
+- [`../plugins/save/save.md`](../plugins/save/save.md), [`auto.md`](../plugins/save/auto.md)