@vnejs/docs 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vnejs/docs",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "VNEJS documentation for engine consumers and coding agents",
   "files": [
     "*.md",

package/plugins/controls/controls.md

@@ -2,7 +2,7 @@
 
 Пакет: `@vnejs/plugins.controls.controls` · namespace: `CONTROLS`
 
-Стек обработчиков абстрактных control-кнопок (push/pop/emit).
+Стек обработчиков абстрактных control-кнопок (push/pop/emit) и текущий тип устройства ввода (keyboard / xbox / playstation).
 
 ## События
 
@@ -11,10 +11,17 @@
 | `EMIT` | `vne:controls:emit` | Инициировать действие или цикл. |
 | `PUSH` | `vne:controls:push` | Добавить элемент в очередь или стек. |
 | `POP` | `vne:controls:pop` | Извлечь элемент из очереди или стека. |
+| `DEVICE_SET` | `vne:controls:device_set` | Запросить смену типа устройства (`{ device }`). |
+| `DEVICE_CHANGED` | `vne:controls:device_changed` | Тип устройства реально сменился (`{ device, prevDevice }`). |
 
 ## Константы
 
-Нет.
+| Ключ | Смысл |
+|------|--------|
+| `BUTTONS` | Абстрактные control-кнопки (`ACCEPT`, `BACK`, …). |
+| `DEVICES.KEYBOARD` | `"keyboard"` |
+| `DEVICES.XBOX` | `"xbox"` |
+| `DEVICES.PLAYSTATION` | `"playstation"` |
 
 ## Параметры
 
@@ -29,6 +36,9 @@
 | Модуль | Зона ответственности |
 |--------|----------------------|
 | `controls` | Обрабатывает EMIT, PUSH, POP. |
+| `controls.device` | Хранит `currentDevice`; на `DEVICE_SET` эмитит `DEVICE_CHANGED` только при реальной смене. |
+
+Источники `DEVICE_SET`: keyboard (keydown) → keyboard; `controls.gamepad.device` (button_press / axis_move) → xbox|playstation по `gamepad.id`; cursor (`mousemove`) → keyboard.
 
 ## Близкие плагины
 
@@ -38,4 +48,6 @@
 
 ### Остальные
 
-— нет
+- [keyboard.md](./keyboard.md) — `KEYBOARD`
+- [gamepad.md](./gamepad.md) — `GAMEPAD`
+- [cursor.md](./cursor.md) — `CURSOR`

package/plugins/controls/cursor.md

@@ -50,7 +50,7 @@
 |--------|----------------------|
 | `cursor` (`Cursor`) | SET_X_Y, resize; владеет `globalState.cursor` (x/y). |
 | `cursor.view_set` (`CursorView`) | VIEW_SET + STATE/STARTED для проставления `view`. Имя `view_set`, чтобы не пересечься с `plugins/views/cursor` (`cursor.view`). |
-| `cursor.move` (`CursorMove`) | MOVE (мышь) → SHOW + SET_X_Y; скрывает системный курсор. |
+| `cursor.move` (`CursorMove`) | MOVE (мышь) → `CONTROLS.DEVICE_SET` (keyboard) + SHOW + SET_X_Y; скрывает системный курсор. |
 | `cursor.shift` (`CursorShift`) | SHIFT + INIT `SHIFT_SPEED` / `SHIFT_REVERSE_*`. |
 | `cursor.click` (`CursorClick`) | CLICK по координатам курсора. |
 | `cursor.scroll` (`CursorScroll`) | SCROLL + INIT `SCROLL_SPEED`. |
@@ -66,4 +66,5 @@
 
 ### Остальные
 
-- [gamepad.md](./gamepad.md) — стики через `compatibility.controls.gamepad-with-controls.cursor`: left → `SHIFT`, right → `SCROLL`
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.DEVICE_SET (mousemove → keyboard)
+- [gamepad.md](./gamepad.md) — стики через `compatibility.controls.gamepad-with-controls.cursor`: left → `SHIFT`, right → `SCROLL`; тип устройства (xbox|ps) — `controls.gamepad.device`

package/plugins/controls/gamepad.md

@@ -6,7 +6,9 @@
 
 ## События
 
-Нет.
+| Ключ | Строка | Смысл |
+|------|--------|-------|
+| `EMIT` | `vne:gamepad:emit` | Проксировать нажатие в `CONTROLS.EMIT` (`{ keys }`) с lock `inProcess`. |
 
 ## Константы
 
@@ -22,7 +24,7 @@
 
 ## Маппинг кнопок (W3C / Xbox standard)
 
-После того как joypad выдаёт логическое имя `button_N`, плагин эмитит ключи в `CONTROLS.EMIT`:
+После того как joypad выдаёт логическое имя `button_N`, модули кнопок и триггеров эмитят `GAMEPAD.EMIT`, а `controls.gamepad` проксирует ключи в `CONTROLS.EMIT`:
 
 | joypad | Физическая (standard) | Абстрактный control |
 |--------|----------------------|---------------------|
@@ -74,7 +76,9 @@ Electron при `STEAM_DECK=1` добавляет `?steamDeck=1`.
 
 | Модуль | Зона ответственности |
 |--------|----------------------|
-| `controls.gamepad` | Подмодуль `gamepad` плагина. |
+| `controls.gamepad` | `connect` / `disconnect` → sync профиля; `GAMEPAD.EMIT` → `CONTROLS.EMIT` с lock `inProcess`. |
+| `controls.gamepad.buttons` | `button_press` / `button_release` → `GAMEPAD.EMIT`; lock активного пада. |
+| `controls.gamepad.device` | `button_press` / `axis_move` → `CONTROLS.DEVICE_SET` (`DEVICES.XBOX` или `DEVICES.PLAYSTATION` по `gamepad.id`). |
 
 ## Близкие плагины
 
@@ -84,5 +88,5 @@ Electron при `STEAM_DECK=1` добавляет `?steamDeck=1`.
 
 ### Остальные
 
-- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, CONST.BUTTONS
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, EVENTS.DEVICE_SET (через `controls.gamepad.device` → xbox|playstation), CONST.BUTTONS, CONST.DEVICES
 - [cursor.md](./cursor.md) — через `compatibility.controls.gamepad-with-controls.cursor`: left stick (оси 0–1) → `CURSOR.SHIFT`, right stick (оси 2–3) → `CURSOR.SCROLL`; RT → `CURSOR.CLICK`

package/plugins/controls/keyboard.md

@@ -34,4 +34,4 @@
 
 ### Остальные
 
-- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, CONST.BUTTONS
+- [controls.md](./controls.md) — `CONTROLS`: EVENTS.EMIT, EVENTS.DEVICE_SET, CONST.BUTTONS, CONST.DEVICES

package/plugins/views/controls.hints.md

@@ -0,0 +1,56 @@
+# plugins/views/controls.hints/
+
+Пакет: `@vnejs/plugins.views.controls.hints` · namespace: `CONTROLS_HINTS`
+
+Оверлей подсказок кнопок (keyboard / xbox / playstation). Группы из `PARAMS.GROUPS` показываются и прячутся по событиям из конфига; иконки переключаются по `CONTROLS.DEVICE_CHANGED`.
+
+## События
+
+| Ключ | Строка | Смысл |
+|------|--------|-------|
+| `UPDATE` | `vne:controls_hints:update` | Обновить состояние или отображение. |
+
+## Константы
+
+Нет.
+
+## Параметры
+
+| Ключ | Тип | Смысл |
+|------|-----|-------|
+| `GROUPS` | `ControlsHintsGroup[]` | Группы подсказок (position, direction, show/hide events, controls). |
+| `LOC_LABEL` | `string` | Метка locs (`controlsHints`). |
+| `TRANSITION` | `number` | Длительность перехода View. |
+| `ZINDEX` | `number` | Fallback z-index группы, если не задан в `position.zIndex`. |
+| `VIEW_PROPS` | `object` | Стили `icon` / `text` / `controlFlex` / `groupFlex`. |
+
+Для экрана обычно задают `position.zIndex = PARAMS.<SCREEN>.ZINDEX + 100`, чтобы другие экраны могли перекрыть подсказки.
+
+Появление/скрытие группы анимируется через `View` с `transition={PARAMS.TRANSITION}` (по умолчанию `300` ms). Группа видима, если `isShow` и есть контролы для текущего device (с учётом `hideOnDevices`). При уходе в пустой список (например keyboard) предыдущие иконки держатся до конца transition, чтобы fade-out успел отрисоваться.
+
+Элемент `controls[]`: `{ locKey, keyboard: string[], xbox: string[], playstation: string[], hideOnDevices?: ControlsDevice[] }` — пути внутри `media/view/{quality}/` (ведущий `/` снимается). `hideOnDevices` — девайсы, на которых контрол не рендерится (`CONTROLS.DEVICES.*`).
+
+## Настройки
+
+Нет.
+
+## Модули
+
+| Модуль | Зона ответственности |
+|--------|----------------------|
+| `controls.hints.controller` | Preload иконок на `SYSTEM.STARTED` / `MEMORY.CLEARED`; show/hide групп; `DEVICE_CHANGED`; `COMPONENTS.EXTERNAL_UPDATE` → `updateViewFast`. |
+| `controls.hints.view` | Рендер нескольких `View` + `Flex` + `Icon` + `Text`. |
+
+## Близкие плагины
+
+### plugins/core/
+
+- [components.md](../core/components.md) — `COMPONENTS`: EXTERNAL_UPDATE
+- [media.md](../core/media.md) — `MEDIA`: LOAD
+- [memory.md](../core/memory.md) — `MEMORY`: CLEARED
+- [state.md](../core/state.md) — `STATE`: SET, CLEAR
+- [system.md](../core/system.md) — `SYSTEM`: STARTED
+
+### Остальные
+
+- [controls.md](../controls/controls.md) — `CONTROLS`: DEVICE_CHANGED, DEVICES