Update project configuration and plugin version. Added autoload for game helper and enabled AI plugin in project settings. Updated plugin version to 3.1.5 for compatibility improvements.

2026-08-12 09:58:04 +03:00
parent 4c98764680
commit 5529198314
28 changed files with 272 additions and 1 deletions
@@ -0,0 +1,78 @@
+# Архитектура
+
+Документ описывает, как устроен проект: какие есть слои, кто кому имеет право
+звонить и как данные ходят по системе. Структура папок — прямое отражение этих
+слоёв, см. [README](../README.md#структура-репозитория).
+
+## Слои и правила зависимостей
+
+Стрелка «→» читается как «может знать о». Всё, что не указано, — запрещено.
+
+```
+main ──→ autoload ──→ core
+  │
+  ├───→ ui ────────→ core, data
+  ├───→ world ─────→ core, data, entities
+  ├───→ systems ───→ core, data
+  ├───→ entities ──→ core, data
+  └───→ debug ─────→ (всё, только для разработки)
+```
+
+| Слой | Зачем | Чего в нём быть не должно |
+| --- | --- | --- |
+| `core` | Утилиты, базовые типы, математика сетки | Ссылок на конкретные сцены и геймплей |
+| `data` | Описания контента: схемы (`Resource`) и их экземпляры (`.tres`) | Логики поведения — только данные |
+| `systems` | Симуляция мира: время, климат, погода, экономика | Прямого доступа к нодам сцены |
+| `world` | Визуализация и взаимодействие с убежищем | Правил симуляции — они в `systems` |
+| `entities` | Жители, предметы; их состояние и поведение | Знания о конкретном UI |
+| `ui` | Экраны, HUD, контролы | Изменения состояния мира напрямую |
+| `debug` | Дев-консоль, оверлеи, читы | Кода, от которого зависит релизная логика |
+
+Ключевое правило: **`ui` и `world` не меняют состояние мира сами** — они шлют
+намерение (сигнал/вызов системы), а изменение делает `systems`. Обратно
+`systems` не дёргает ноды: он сообщает об изменении сигналом.
+
+## Данные и рендер разделены
+
+Симуляция не должна зависеть от того, нарисовано ли что-то на экране.
+
+- **Данные** (`systems`, `data`) — чистая логика: считаются от `delta`, полностью
+  сериализуемы, тестируются без дерева сцены.
+- **Рендер** (`world`, `ui`) — читает данные и отображает, подписавшись на сигналы.
+
+Практический критерий: любой класс из `systems` должен работать в юнит-тесте,
+где никакой сцены нет.
+
+## Обмен сообщениями
+
+Три способа, в порядке предпочтения:
+
+1. **Сигнал вверх, вызов вниз.** Родитель знает о детях и вызывает их методы;
+   ребёнок о родителе не знает и только испускает сигналы.
+2. **Ссылка на систему**, полученную из автозагрузки — когда нужен ответ здесь и
+   сейчас (запрос состояния, валидация постройки).
+3. **Глобальная шина (`EventBus` в `autoload`)** — только для событий, которые
+   слушают несколько несвязанных слоёв (например, «время перескочило»,
+   «погода сменилась»). Не превращать её в свалку: каждый сигнал документируем.
+
+## Контент — это ресурсы, а не код
+
+Новая комната, предмет или тип породы добавляются как `.tres` в `data/tables/`
+по схеме из `data/resources/`, без правки кода. Если для добавления контента
+приходится менять `.gd` — схема неполная, чинить надо схему.
+
+## Автозагрузки
+
+Автозагрузка — дорогая вещь: она живёт всю сессию и её видно отовсюду. Заводим
+только для того, что действительно глобально и одно на игру. Каждая новая
+автозагрузка регистрируется через *Project Settings → Autoload* и упоминается
+здесь.
+
+Сейчас в проекте: `_mcp_game_helper` — служебная, часть плагина `godot_ai`,
+к игровой логике отношения не имеет.
+
+## Решения
+
+Существенные развилки (выбор подхода к сохранению, к сетке, к тайм-степу)
+фиксируем как ADR в [`adr/`](adr/) — короткая заметка «контекст → решение →
+последствия». Это дешевле, чем через полгода восстанавливать мотивацию по коду.