# R2D DevTools

## Цель

Дать инструменты разработчика, **не нарушая code-first философию** R2D
([PHILOSOPHY.md](PHILOSOPHY) §2.2).

DevTools — это **инспектор и отладчик**. Это **не** каноническая среда
авторинга игры: уровень и логика по-прежнему описываются кодом и данными.
DevTools ничего не «сохраняет как проект» и не становится источником истины.

Статус: план ([ROADMAP.md](ROADMAP) фаза 8).

---

## 1. Технология UI

**Весь UI DevTools делается на RmlUi.** См. [UI_RMLUI_LAW.md](UI_RMLUI_LAW):
никаких новых ImGui-окон, никакого второго developer GUI.

Нативные custom-элементы внутри RmlUi **разрешены** — ровно для
специализированного отрисованного содержимого (см. §4). RmlUi владеет
окружающим интерфейсом, вёрсткой и раскладкой.

---

## 2. Панели (кандидаты)

```text
WORLD
ENTITIES
EVENTS
PHYSICS
BSP
NAV
AUDIO
RENDER
PERF
AGENT
```

---

## 3. Инспектор сущности

Выбор `#hero` может показывать:

```text
#hero

Transform
  position
  rotation
  scale

Physics
  velocity
  body
  contacts

Gameplay
  health
  state

Events
  recent events

Debug
  source
  prefab
  trace
```

Значения, безопасные для изменения, **могут** правиться на лету — но см. §6
(источник истины).

---

## 4. Визуализация

Нативные custom-элементы RmlUi **могут** визуализировать:

* формы коллизий;
* BSP;
* навигацию;
* пространственные индексы;
* зоны видимости;
* графики профайлера.

---

## 5. Выбор сущности (picking)

Клик по сущности в превью мира должен давать **ту же идентичность**, что
понимает `$`:

```text
кликнули сущность → #goblin_12
```

DevTools должен позволять **скопировать полезный селектор**.

---

## 6. Источник истины

Временное изменение значения через DevTools **не должно** молча становиться
каноническими данными проекта. Там, где это уместно, предоставляются явные
действия:

```text
Copy value
Copy selector
Copy JS
Export override
```

Пример:

```js
$('#guard').at(420, 120);
```

---

## 7. Интеграция с агентом

DevTools и агентский протокол **должны опираться на один introspection API**.
Нельзя независимо реализовывать «инспекцию для DevTools» и «инспекцию для
агента» с несовместимой семантикой.

```text
            Debug/Inspection API
               /            \
            RmlUi          Agent
           DevTools        Protocol
```

---

## 8. Критерии приёмки

DevTools умеет:

* список сущностей;
* выбор одной;
* инспекцию базового состояния;
* показ метрик движка;
* использование **только RmlUi** для обычного интерфейса;
* работу, не превращаясь в источник истины.

Первый полезный срез (из [ROADMAP.md](ROADMAP) фаза 8):

```text
список сущностей → выбрать → инспекция свойств →
transform/physics/state → скопировать селектор
```

---

## 9. Что уже есть в движке

**Первый срез DevTools сделан (2026-10-07): `$.devtools`** — панель
«список сущностей → выбор → свойства → скопировать селектор», целиком на RmlUi
(документ собирается кодом через `engine.ui.loadMarkup`, `.rml` в игре не
нужен). Открывается по **F2**: [highlevel/devtools.md](highlevel/devtools).

Что в нём уже есть:

| Требование §8 | Состояние |
|---|---|
| Список сущностей | ✅ до 24 строк из `$.agent.nodes('*')` |
| Выбор одной | ✅ клик по строке или `$.devtools.selectBy('#hero')` |
| Инспекция базового состояния | ✅ transform, тело, здоровье, команда, живость, видимость, `aria` |
| Метрики движка | ⬜ панель PERF пока не подключена (есть `$.debug.profile()`) |
| Только RmlUi для обычного интерфейса | ✅ ImGui не используется |
| Не источник истины | ✅ панель только читает и копирует селектор |

Чего ещё нет: правки значений на лету, визуализации коллизий/BSP/навигации,
таймлайна событий, панелей WORLD/EVENTS/AUDIO/RENDER, «Copy JS / Export
override». Заготовки для них — ниже.

| Заготовка | Что даёт | Где |
|---|---|---|
| `$.agent.snapshot()` | `frame, time, dt, fps, paused, scene, window, camera, world, entities[], ui[], player, tests` + поля `expose` | [agent.js:76-120](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/agent.js) |
| `$.agent.node(sel)` / `nodes(sel)` | краткое описание узла / список описаний | [agent.js:24-46](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/agent.js), [:58-67](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/agent.js) |
| `$.agent.expose(name, fn)` | свои поля в снимке | [agent.js:70-73](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/agent.js) |
| `engine.setSnapshot` | снимок уходит в ответ на команду `state` | [agent.js:123-126](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/agent.js), [agent.c:195-225](https://github.com/Nikide/russiano2d/blob/main/src/agent.c) |
| `$.debug.stats()` / `counters()` / `limits()` | счётчики, занятость и потолки таблиц | [debug.js:33-71](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/debug.js) |
| `$.debug.profile()` | зоны кадра, GPU-время, пики | [script.c:358-391](https://github.com/Nikide/russiano2d/blob/main/src/script.c), зоны [profile.h:41-48](https://github.com/Nikide/russiano2d/blob/main/src/profile.h) |
| `$.debug.profiler.*` | свои замеры | [debug.js:145-221](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/debug.js) |
| `$.debug.draw.*`, `$.debug.watch()` | отладочная отрисовка и наблюдения (принимают селекторы) | [debug.js:72-118](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/debug.js) |
| `engine.depthInfo()`, `engine.fontStats()`, `engine.renderInfo()` | глубина/меш, атлас глифов, проходы рендера | [script.c:4028](https://github.com/Nikide/russiano2d/blob/main/src/script.c), [:4190](https://github.com/Nikide/russiano2d/blob/main/src/script.c) |
| Курсор и выбор в мире | `attrs.picked`/`hovered` | [api.js:1851-1890](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/api.js) |
| Диагностика F1 (RmlUi) | статистика, профиль, физика, текстуры, скрипты, watches | [devtools.js](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/devtools.js) |

**Чего ещё нет:**

* правок значений на лету и их экспорта (value / JS / override);
* picking из мира в панель: клик/ховер по узлам интерфейса есть
  ([ui.js:160-202](https://github.com/Nikide/russiano2d/blob/main/src/highlevel/ui.js)), но клик по спрайту в
  сцене пока не превращается в селектор панели;
* панелей WORLD / EVENTS / PHYSICS / BSP / NAV / AUDIO / RENDER / PERF —
  уже есть диагностика статистики/профиля, гравитации, скриптов и текстур; специализированные визуализации остаются;
* визуализации коллизий, BSP, навигации и зон видимости как инструмента
  (есть только ручные примитивы `$.debug.draw`);
* таймлайна событий — `$.watch` (реактивные запросы) даёт материал, но
  панели на нём ещё нет.

**ImGui удалён (2026-10-09).** F1, `--overlay` и `$.debug.on()` используют
RmlUi диагностику существующего DevTools, F2 — инспектор узлов.

---

## 10. Связанные документы

[UI_RMLUI_LAW.md](UI_RMLUI_LAW) — закон интерфейса,
[AGENT_API.md](AGENT_API) и [highlevel/agent.md](highlevel/agent) —
агентский протокол и снимок, [highlevel/debug.md](highlevel/debug) —
`$.debug`/`$.console`, [ROADMAP.md](ROADMAP) — фаза 8.