# Модульная система «Богатырей»

Игра собрана из девяти модулей вокруг общего **Игрового ядра**. Модули общаются только через контракты и события ядра и не управляют внутренним кодом друг друга. Это правило проверяет сам Unity: каждый модуль — отдельная сборка (`.asmdef`), которая видит только ядро, поэтому прямое обращение к соседнему модулю не скомпилируется.

```
                        Игровое ядро (Bogatyri.Core)
          контракты (IEconomy, IArmy...) · события (EventBus) · реестр (GameServices)
   ┌───────────┬────────────┬───────────┬──────────────┬───────────────┬────────────┬──────────┬──────────┐
 Экономика  Поселение     Армия    Глобальный мир  Боевая система  Сохранения     Чат        Круг
 ресурсы,   здания,      войска,   карта,          урон, потери,   игровое        мир и      объединение
 производство развитие   характеристики перемещения  исход           состояние      Круг       игроков
                        ▲
            App/GameModules — точка сборки: регистрирует модули и соединяет их события
            со старыми системами (GameProgress, Казармы, панели UI)
```

| Модуль | Сборка | Папка | Документ |
| --- | --- | --- | --- |
| Игровое ядро | `Bogatyri.Core` (без Unity), `Bogatyri.Core.Unity` | `Assets/Scripts/Modules/Core`, `Core.Unity` | [Core.md](Core.md) |
| Экономика | `Bogatyri.Economy` | `Assets/Scripts/Modules/Economy` | [Economy.md](Economy.md) |
| Поселение | `Bogatyri.Settlement` | `Assets/Scripts/Modules/Settlement` | [Settlement.md](Settlement.md) |
| Армия | `Bogatyri.Army` (без Unity) | `Assets/Scripts/Modules/Army` | [Army.md](Army.md) |
| Население | `Bogatyri.Population` (без Unity) | `Assets/Scripts/Modules/Population` | [Population.md](Population.md) |
| Глобальный мир | `Bogatyri.World`, `Bogatyri.World.Simulation` (без Unity) | `Assets/Scripts/Modules/World` | [World.md](World.md) |
| Боевая система | `Bogatyri.Battle` (без Unity) | `Assets/Scripts/Modules/Battle` | [Battle.md](Battle.md) |
| Сохранения | `Bogatyri.Save` | `Assets/Scripts/Modules/Save` | [Save.md](Save.md) |
| Чат | `Bogatyri.Chat` (без Unity) | `Assets/Scripts/Modules/Chat` | [Chat.md](Chat.md) |
| Круг | `Bogatyri.Circle` (без Unity) | `Assets/Scripts/Modules/Circle` | [Circle.md](Circle.md) |

## Правила

1. **Модуль ссылается только на ядро.** Нужен соседний модуль — получи его контракт: `GameServices.Get<IEconomy>()`. Никаких `ResourceManager.Instance` внутри модулей.
2. **Факты — событиями.** Случилось что-то, о чём другим стоит знать, — `EventBus.Publish(new ...Event{...})`. Подписчик обязан отписаться в `OnDestroy`.
3. **Каждый модуль сам сохраняет свои данные** — реализует `ISaveParticipant` и регистрируется в `SaveRegistry`. Модуль Сохранений не знает, что внутри секций.
4. **Правила игры — без Unity и без `float`, где это возможно** (Армия, Бой, симуляция Мира). Этот код без изменений сможет работать на сервере.
5. **Слой приложения** (`Assets/Scripts`, вне `Modules`) — интерфейс, панели, `GameProgress`. Ему можно обращаться к модулям напрямую. Переносить оттуда логику в модули — постепенно, по плану.
6. **Вся «проводка» — в `App/GameModules.cs`.** Новую связь между модулем и остальной игрой добавляй туда, а не внутрь модуля.

## Как вести документы модулей

- **Изменил модуль — обнови его документ в том же коммите.** Новый метод контракта, событие, секция сохранения, файл — всё это в разделах документа.
- **В «Журнал изменений» добавляй строку сверху:** дата, кто, что изменилось. Так видно историю модуля без чтения кода.
- **Решение команды, которое касается модуля,** записывай в раздел «Решения и план» со ссылкой на источник (например, «план от 19.10.2026»).
- **Новый модуль** — новый файл по образцу `Economy.md` и строка в таблице выше.

## Тесты

EditMode-тесты: `Assets/Scripts/Modules/Tests/ModuleTests.cs`. Запуск: **Window → General → Test Runner → EditMode → Run All**.

Уже есть: Армия (поход не создаёт и не теряет солдат, потери по типам, сохранение, перенос старых данных, сброс), Круг (основание, вступление, выход, полный Круг, сохранение), канал «Круг» в чате только для участников, чат (пустое сообщение, обрезка длинного, событие, предел истории), деление войск без двойного учёта и без потерь, бой (больше солдат — победа, ничья — защитнику), поход с офлайн-прогрессом, шина событий (ошибка подписчика не ломает остальных), реестр модулей.

Добавить вместе с этапами 1, 2 и 5 (решение команды от 19.10.2026):

- [x] лимит жилья: 300 жителей при лимите 300 — прирост стоит, предел вырос — прирост идёт (`PopulationTests`; пока предел растёт от Ратуши, Дома ещё нет);
- [ ] нельзя призвать ниже гражданского резерва: 150 свободных, резерв 30 → призвать можно не больше 120;
- [ ] назначение гарнизона: 30 солдат, 10 в гарнизон → 20 доступны, всего по-прежнему 30 (основа — тест «один солдат в одном месте» для походов уже есть);
- [ ] голод и восстановление: еда кончилась → дебаффы, в том числе у защитников; еда вернулась → снятие по правилу;
- [ ] предел синих кристаллов: кристаллы не копятся бесконечно, сверх лимита — по общему правилу.

## Журнал изменений

| Дата | Кто | Что |
| --- | --- | --- |
| 26.10.2026 | Claude | Модуль Населения ([Population.md](Population.md)), таблица баланса `EconomyConfig` (`Assets/Resources/EconomyConfig.asset`), часы игры `GameClock`, отладочная панель «DEV». Обновлены Core, Economy, Save. |
| 23.10.2026 | Claude | Окно «ВОЙСКО ВЕРНУЛОСЬ» в городе (`UI/MarchReturnPopup.cs`), обновлён World. |
| 23.10.2026 | Claude | Войска переехали в модуль Армии (`ArmyService`, секция `army`), `ArmyBridge` удалён. Обновлены Army, Core, Save. |
| 19.10.2026 | Claude | Оставлена одна карта мира (сцена WorldMap). Маленькая карта `Meta/World` удалена с переносом солдат из её походов. Обновлены World и Army. |
| 19.10.2026 | Claude | Добавлен модуль Круга (`Bogatyri.Circle`, [Circle.md](Circle.md)): основать, вступить, выйти, роли, окно «Круг» на карте мира. Канал «Круг» в чате привязан к Кругу игрока. |
| 19.10.2026 | Claude | Добавлен модуль Чата (`Bogatyri.Chat`, [Chat.md](Chat.md)) с разворотом на весь экран. В сцене города кнопка «ПОЧТА» привязана к правому краю нижней панели — в безопасной зоне она уезжала за экран. |
| 19.10.2026 | Claude | Слой приложения: HUD города и карты мира учитывает Safe Area (`UI/SafeArea.cs`, `UI/SafeAreaInstaller.cs`). Элементы, растянутые на весь экран, остаются на весь экран. |
| 19.10.2026 | Claude | Добавлен сброс сохранений (Настройки, меню Tools, `ISaveSystem.ResetAll`). Обновлены Core, Economy, Settlement, World, Save. |
| 19.10.2026 | Claude | Создана модульная система: ядро, шесть модулей, точка сборки `App/GameModules`, тесты, документы модулей. Ветка `feature/modules`. |