# Философия Russiano2D

Это **конституция движка**: короткий список решений, которые не обсуждаются
заново на каждой задаче. Документ написан и для людей, и для агентов: он
называет, что можно менять свободно, а что является архитектурной константой.

Статус: **ограничения, а не пожелания**. Изменение здесь — отдельное решение
владельца проекта, а не побочный эффект правки кода.

Детали и история: [ARCHITECTURE.md](ARCHITECTURE) (философия API `$`),
[TASKS.md](TASKS) (сверка с Godot 4.x),
[TASKS.md](TASKS) (что осталось). Законы, вытекающие отсюда:
[UI_RMLUI_LAW.md](UI_RMLUI_LAW) и
[AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES).

---

## 1. Что такое Russiano2D

2D-игровой движок: ядро на C/C++ (SDL3 + SDL_GPU, Box2D v3, QuickJS-ng,
SDL3_mixer, RmlUi), игровая логика — JavaScript. Вся работа с движком идёт
через одну точку входа — `$` в стиле jQuery. Схема — **C → `$`**: нативное ядро
отдаёт свои примитивы прямо модулям `$`, а игре виден только `$`. Низкоуровневого
`engine.*` в игровом коде нет — до него не добраться без пересборки движка
([highlevel/native.md](highlevel/native)).

Игра — это **код и данные**, а не проект в визуальном редакторе: уровень,
логика и интерфейс описываются текстом, поэтому их удобно читать, diff'ить,
генерировать и проверять автоматически, в том числе ИИ-агентом.

**RE2D — spatial description → projection → ordinary 2D representation.**
XYZ/surfaces/bones/depth — промежуточные authoring/runtime-данные синтеза;
результат — обычный 2D sprite/кадр для существующего R2D 2D-батча.
RE2D World продолжает этот принцип: XY BSP + vertical spans, специализированные
стены и регионы пола/потолка. Пространственная математика не вводит обычный
3D scene graph, универсальный world mesh API или 3D-физику. Сущности и gameplay
остаются узлами/компонентами и скриптами. Совместимый прежний Re2D-путь
(`.kind(Re2D)`, `room`, `mesh`) описан в [RE2D.md](RE2D); его mesh-проход
не является архитектурной целью нового World. Узлы и камеры без `kind`
работают как прежде.

---

## 2. Константы

1. **`$` — единственная точка входа.** Одно пространство имён, цепочки,
   селекторы, неявная итерация. Нативное ядро — внутренность `$`
   (`src/highlevel/native.js`): `globalThis.engine` после установки `$`
   убирается, внутренние модули `r2d/*` игре не импортируются. Чего игре не
   хватает — добавляется в `$`, а не открывается наружу.
2. **Канонического редактора сцен нет и не планируется.** Уровень и логика —
   код и данные. Инструменты разработчика ([DEVTOOLS.md](DEVTOOLS)) —
   инспектор. Инструменты [SDK](SDK) редактируют открытые JSON/PNG и
   показывают их существующим runtime; они не создают обязательный project
   format, второй scene graph или скрытое состояние, без которого игра не работает.
   Это граница существующего code/data-first принципа, а не смена архитектуры.
3. **Создание как в HTML, поиск как в CSS.** `$('<player>', { id: 'hero' })`,
   `$('#hero')`, `$('.enemy:alive')`. Никаких `new`, `extends`, `this` в
   игровом коде.
4. **Кадр — пакет.** Игра не вызывает отрисовку на спрайт: `$.gfx` собирает
   массивы и отдаёт их одним вызовом (`engine.submitSprites` и родственные).
5. **C — ядро `$`, JS — его API и оркестрация.** Покадровые проходы по узлам
   `$` (синк физики, события мира, наведение, сортировка, сборка батча, твины)
   идут в C прямо над узлами (`src/nodes.c`, [highlevel/native.md](highlevel/native)),
   а не поштучными переходами C↔JS. Модули `$` на JS дают API, редкие и
   сложные случаи; произвольную игровую логику в C не переносят. См. правило 5
   в [AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES).
6. **Весь интерфейс — RmlUi.** Игровой UI, HUD, меню, диалоги, DevTools:
   только `.rml` + `.rcss`. Подробности и переходное правило —
   [UI_RMLUI_LAW.md](UI_RMLUI_LAW).
7. **Человек и агент — равные потребители.** Машинно-ориентированные API
   отдают структурированные данные, а не декоративный текст; движок сообщает
   только известные ему факты и не сочиняет объяснений (правила 8–9 в
   [AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES)).
8. **Детерминизм — инструмент отладки, а не роскошь.** Фиксированный шаг
   (`--fixed-dt`), зерно (`--seed`), управляемый ввод и запись/воспроизведение
   делают баг воспроизводимым. См. [RECORD_REPLAY.md](RECORD_REPLAY) и
   [TESTING.md](TESTING).
9. **Существующий код побеждает.** Сначала найди существующую подсистему, её
   доку и тесты; параллельная реализация «того же, но своего» не принимается.
10. **Совместимость.** Существующие игры продолжают работать; ломающее
    изменение публичного поведения требует обоснования, заметок о миграции и
    тестов.
11. **Измерять, а не верить.** Утверждение «стало быстрее» без замера до/после,
    числа объектов и конфигурации сборки не принимается (правило 6 в
    [AGENT_IMPLEMENTATION_RULES.md](AGENT_IMPLEMENTATION_RULES)).

---

## 3. Явные non-goals

Перечисленное **не** является задачей и не должно появляться «попутно»:

* переписывание движка или переезд на C++;
* ECS и другие смены архитектурной парадигмы;
* замена QuickJS-ng, SDL3 или RmlUi;
* второй UI-фреймворк (включая «временный» ImGui-интерфейс — см. закон UI);
* визуальный редактор сцен вместо кода;
* новый физический движок;
* преждевременный общий фреймворк R2D/R3D
  ([R2D_R3D_CONVENTIONS.md](R2D_R3D_CONVENTIONS)).

---

## 4. Чем это проверяется

* `python3 tools/run_tests.py` — агентские интеграционные тесты
  ([TESTING.md](TESTING));
* `tests/js/*_test.mjs` под QuickJS — логика подсистем без движка;
* `python3 tests/doc_claims_test.py` — страж «в доке написано, что чего-то
  нет, а в коде оно есть»;
* `python3 tests/doc_coverage_test.py` — у каждого модуля `src/highlevel/*.js`
  есть страница и тест;
* `tests/agent/engine_hidden_test.py` — игре виден только `$` (константа 1);
* `tests/agent/native_passes_test.py` — нативные проходы кадра дают тот же
  кадр, события и значения, что JS-путь (константа 5).

Правило на будущее: **закрытый пункт работы в том же изменении исчезает из
документации** — старые находки остаются в истории Git, а [TASKS.md](TASKS) содержит
только актуальные ограничения и следующий шаг.