# Конвенции Russiano (R2D и R3D)

R2D (Russiano2D) и R3D (Russiano3D) — **отдельные движки/проекты**.

Они **должны** разделять полезные ментальные модели разработчика.

Они **не должны** загоняться в общую абстракцию, если это вредит хотя бы
одному из движков.

Статус: конвенция на будущее. В репозитории R2D проекта R3D **нет**: в коде
(`src/`) и тестах ни одного упоминания, `R3D` встречается только в этом
документе и в [PHILOSOPHY.md](PHILOSOPHY)/[ROADMAP.md](ROADMAP) как план.
Поэтому ничто здесь не описывает существующий код R3D — это договорённость о
совместимых понятиях и именах.

---

## 1. Общие понятия

Предпочтительна совместимая терминология для:

```text
World
Entity
Selector
Query
Event
Prefab
Asset
Scene
UI
Agent
Inspect
Replay
```

Термины означают одно и то же в обоих движках, даже если синтаксис API
различается.

---

## 2. Выбор сущностей

R2D:

```js
$('.enemy')
```

R3D может использовать:

```js
Q('.enemy')
```

или другой одобренный проектом эквивалент. **Семантическая согласованность
важнее идентичного синтаксиса.**

---

## 3. Философия запросов

Оба движка предпочитают

```text
select → filter → operate
```

повторяющемуся высокочастотному перебору в JS. Массовая операция над выборкой
должна выполняться одним проходом, а не поштучными переходами через границу
C↔JS ([PHILOSOPHY.md](PHILOSOPHY) §2.5,
[AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES) правило 5).

---

## 4. UI

Оба движка используют один и тот же фундаментальный закон:

> **ALL UI → RmlUi**

Нативный отрисовщик движка может появляться **внутри специализированных
custom-элементов** (визуализация геометрии, графики), но не вместо RmlUi и не
рядом с ним как второй интерфейсный стек. Для R2D это
[UI_RMLUI_LAW.md](UI_RMLUI_LAW); R3D следует той же формулировке.

---

## 5. Агентский протокол

Где это практично, **имена команд должны совпадать**:

```text
step
query
inspect
screenshot
profile
```

Полезные нагрузки (payload) могут отличаться там, где этого требуют 2D/3D
семантики. Структурированные факты и запрет спекулятивных объяснений —
общие ([PHILOSOPHY.md](PHILOSOPHY) §2.7,
[AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES) правила 8–9).

---

## 6. Не создавать «Russiano Common Framework» преждевременно

Общий код **должен** существовать, потому что решает реальную задачу
сопровождения.

Он **не должен** существовать только потому, что у R2D и R3D похожие имена.

Скопировать маленькое понятие дважды может быть дешевле, чем вечно
поддерживать неверную абстракцию. Это же записано в non-goals:
[PHILOSOPHY.md](PHILOSOPHY) §3, [ROADMAP.md](ROADMAP) «Явные non-goals».

---

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

[PHILOSOPHY.md](PHILOSOPHY) — конституция R2D,
[UI_RMLUI_LAW.md](UI_RMLUI_LAW) — закон UI,
[AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES) — правила
работы агентов, [AGENT_API.md](AGENT_API) — агентский протокол R2D.