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

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

```
                ┌─────────────────────────────────────────┐
                │        ОБЩЕЕ ИГРОВОЕ ЯДРО (Core)         │
                │ контракты · события · реестр · время игры │
                └─────────────────────────────────────────┘
            все модули видят только ядро, друг друга — нет

┌──────────────────────┐  ┌──────────────────────┐
│ ЭКОНОМИКА            │  │ ПОСЕЛЕНИЕ            │
│ ресурсы, склады,     │  │ здания, Ратуша,      │
│ лимиты, добыча       │  │ участки, стройка     │
│ рабочими             │  │                      │
└──────────────────────┘  └──────────────────────┘
┌──────────────────────┐  ┌──────────────────────┐
│ НАСЕЛЕНИЕ            │  │ АРМИЯ                │
│ люди, рабочие, еда,  │  │ воины по типам: дома,│
│ голод, прирост,      │  │ в гарнизоне,         │
│ жильё                │  │ в походе             │
└──────────────────────┘  └──────────────────────┘
┌──────────────────────┐  ┌──────────────────────┐
│ ГЛОБАЛЬНЫЙ МИР       │  │ БОЕВАЯ СИСТЕМА       │
│ карта, походы, замок,│  │ сила, контры, стены, │
│ соседи, лагеря       │  │ удача ±5%, голод,    │
│ разбойников          │  │ прогноз              │
└──────────────────────┘  └──────────────────────┘
┌──────────────────────┐  ┌──────────────────────┐
│ КРУГ                 │  │ ЧАТ                  │
│ объединение игроков, │  │ общий мир и чат      │
│ роли                 │  │ Круга                │
└──────────────────────┘  └──────────────────────┘
┌──────────────────────┐
│ СОХРАНЕНИЯ           │
│ save.json, у каждого │
│ модуля своя секция   │
└──────────────────────┘

App/GameModules — точка сборки: регистрирует модули и соединяет их события
со старыми системами (GameProgress, Казармы, панели UI)
```

**Не путать:**

- **Поселение** — это **здания**: что построено и какого уровня. **Население** — это **люди**: сколько их, кто работает, сколько едят. Связь: уровень Ратуши (Поселение) задаёт предел жилья (Население).
- **Армия** хранит, где стоит каждый воин. **Боевая система** только считает бой: кто победил и кто погиб.
- **Глобальный мир** решает, куда и когда идёт войско; бой он просит у Боевой системы.
- **Производство** (`Bogatyri.Economy.Rules`) — не отдельный модуль, а часть Экономики без Unity: добыча через рабочих.

**Кто отвечает** (договорённость команды от 27.10.2026):

| Кто | Модули |
| --- | --- |
| Валдемар (экономика) | Экономика, Население |
| Саша (война и карта) | Армия, Боевая система, Глобальный мир, Круг, Чат, Разведка |
| Общее | Ядро, Поселение, Сохранения |

| Модуль | Сборка | Папка | Документ |
| --- | --- | --- | --- |
| Игровое ядро | `Bogatyri.Core` (без Unity), `Bogatyri.Core.Unity` | `Assets/Scripts/Modules/Core`, `Core.Unity` | [Core.md](Core.md) |
| Экономика | `Bogatyri.Economy`, `Bogatyri.Economy.Rules` (без Unity) | `Assets/Scripts/Modules/Economy` | [Economy.md](Economy.md) |
| Поселение | `Bogatyri.Settlement` | `Assets/Scripts/Modules/Settlement` | [Settlement.md](Settlement.md) |
| Население | `Bogatyri.Population` (без Unity) | `Assets/Scripts/Modules/Population` | [Population.md](Population.md) |
| Армия | `Bogatyri.Army` (без Unity) | `Assets/Scripts/Modules/Army` | [Army.md](Army.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) |
| Разведка | `Bogatyri.Intelligence` (без Unity) | `Assets/Scripts/Modules/Intelligence` | [Intelligence.md](Intelligence.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**.

Уже есть: голод в бою (−50%, с усталостью 40%, у нападающих и защитников, в момент боя), боевой цикл (случайность воспроизводима и в пределах ±5%, прогноз не противоречит бою, итог сходится по типам у обеих сторон, правила из таблицы, тот же поход — тот же бой), безопасная отправка и возвращение (неизвестный поход, повторное возвращение, повторный номер, откат похода), крайние случаи боя (1×1, 1×10, 0×0, предельные бонусы), гарнизон города (свободные и гарнизон, в поход только свободные, потери, сохранение), лагеря разбойников (расстановка, бой в поле, разбит и появляется снова, второе войско находит лагерь пустым, сохранение), бой с типами войск (контры, стены, осадные, потери в пределах состава), состав гарнизонов, Армия (поход не создаёт и не теряет солдат, потери по типам, сохранение, перенос старых данных, сброс), Круг (основание, вступление, выход, полный Круг, сохранение), канал «Круг» в чате только для участников, чат (пустое сообщение, обрезка длинного, событие, предел истории), деление войск без двойного учёта и без потерь, бой (больше солдат — победа, ничья — защитнику), поход с офлайн-прогрессом, шина событий (ошибка подписчика не ломает остальных), реестр модулей.

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

- [x] лимит жилья: 300 жителей при лимите 300 — прирост стоит, предел вырос — прирост идёт (`PopulationTests`; пока предел растёт от Ратуши, Дома ещё нет);
- [x] нельзя призвать ниже гражданского резерва: 150 свободных, резерв 30 → призвать можно не больше 120; резерв по уровню Ратуши 10/20/30 (`PopulationTests`);
- [x] назначение гарнизона: 30 солдат, 10 в гарнизон → 20 доступны, всего по-прежнему 30 (`ArmyService_Garrison_OneSoldierInOnePlace`);
- [ ] голод и восстановление: еда кончилась → дебаффы, в том числе у защитников; еда вернулась → снятие по правилу. Бой уже проверен (`Battle_Famine_HalvesPower_AndStacksWithFatigue`, `World_FamineAtBattleTime_WeakensMarch`: −50% у нападающих и у защитников, вместе с усталостью 40%), история голода на момент боя — `PopulationTests`; добыча кроме еды при голоде ×0.5 и снятие штрафа сразу после еды — `ProductionTests` (31.10);
- [ ] предел синих кристаллов: кристаллы не копятся бесконечно, сверх лимита — по общему правилу.

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

| Дата | Кто | Что |
| --- | --- | --- |
| 04.11.2026 | Claude | Карта мира в 2.5D на примитивах. Обновлены World, Intelligence. |
| 04.11.2026 | Claude | 3D-поселение, этап I — прототип на примитивах (ТЗ от 04.11). Обновлён Settlement. |
| 04.11.2026 | Claude | Решения по отчёту Саши от 01.11: потери сильной стороны до 2% при 10:1, 5 временных мест госпиталя, цена лечения 1 / 1 / 2 / 3 золота. Обновлены Battle, Army. |
| 01.11.2026 | Claude | Здание «Госпиталь» (решения 31.10, п. 7). Обновлены Army, Core, Settlement. |
| 01.11.2026 | Claude | Решения 31.10, п. 7: раненые и госпиталь (логика; здание — следующий шаг). Обновлены Battle, Army, Population, World, Core, Settlement. |
| 01.11.2026 | Claude | Решения 31.10, п. 8: очередь обучения — у Армии. Обновлены Army, Core, Population. |
| 01.11.2026 | Claude | Решения 31.10, п. 2: поход «Разведка». Обновлены World, Core, Intelligence. |
| 01.11.2026 | Claude | Решения 31.10, п. 6: 24 ресурсные точки. Обновлён World. |
| 01.11.2026 | Claude | Решения 31.10, п. 5: разгром дальше 5:1 (92% / 95% / до 99%). Обновлён Battle. |
| 01.11.2026 | Claude | Решения 31.10, п. 4: средняя скорость смешанного войска. Обновлён World. |
| 01.11.2026 | Claude | Решения по 8 вопросам Саши (31.10), п. 1: гарнизоны и запасы точек видны только в зоне обзора. Обновлён Intelligence. |
| 31.10.2026 | Claude | Окна зданий: подписи над зданиями убраны, у каждого здания (добывающие, Дом, Склад, Амбар, Ратуша, Кристалл) своё окно по тапу — состояние, добыча и склад, улучшение и его цена. Казармы тоже получили окно и уровни (открывают новые войска вместе с Ратушей; уровни 1/2/3/5 — ТЕСТ). Ратуша улучшается кнопкой в окне, а не тапом. Обновлён Settlement. |
| 31.10.2026 | Claude | По регламенту 31.10: откат — Население снова самостоятельный модуль (`Modules/Population`, `Bogatyri.Population`), схема и «Кто отвечает» как у Саши. Работать может любой житель (без «40%»), резерв по уровню Ратуши 10/20/30, голод режет добычу кроме еды вдвое. Обновлены Population, Settlement, Economy, Core. |
| 31.10.2026 | Claude | Модуль Разведки, этап М1 ([Intelligence.md](Intelligence.md)): туман, обзор, чужие армии, последний контакт. Патрули-заглушки соседей для проверки. Обновлены World, Core, Save. |
| 31.10.2026 | Claude | Панель армий на карте мира (регламент 31.10). Обновлён World. |
| 31.10.2026 | Claude | Ресурсные точки на карте мира по регламенту 31.10 (наша часть по решению №46: состояние точки и сбор; зачисление — Экономика через `IEconomy`). Обновлены World, Save, Core. |
| 31.10.2026 | Claude | Скорости маршей по типам и слоты похода по регламенту 31.10 (таблица `MarchConfig`). Обновлены World, Army, Core. |
| 31.10.2026 | Claude | Кривая потерь боя по регламенту 31.10 (решение №14). Обновлён Battle. |
| 30.10.2026 | Claude | Мир по документу 02: события строго по времени после офлайна, время и номер боя в событиях похода, единицы у таймеров; тесты «Готово, когда» (порядок, двойная доставка, таймеры, 0/1 солдат). Обновлены World, Core. |
| 30.10.2026 | Claude | Бой по решениям №11–13 комплекта 29.10: шанс победы, сила без промежуточного округления, округление потерь шансом; голод в офлайн-бою по истории Населения. Обновлены Battle, World, Core. |
| 28.10.2026 | Claude | Население стало частью Поселения, как на схеме Димы: `Settlement/Population`, сборка `Bogatyri.Settlement.Population`. Найм воинов из свободных жителей с гражданским резервом, история голода для боя. Обновлены Settlement, Population, Core. |
| 28.10.2026 | Claude | Схема модулей обновлена: десять модулей (добавлено Население), «Не путать» (Поселение и Население, Армия и Боевая система), кто за что отвечает. |
| 28.10.2026 | Claude | Голод в бою (−50%) и правило усталости (−20%, вместе 40%). Обновлены Battle, World, Core. |
| 28.10.2026 | Claude | Этап 2 плана, начало: таблица баланса боя `BattleConfig`, случайность ±5%, прогноз риска, полный итог боя для обеих сторон. Обновлены Battle, World, Core. |
| 28.10.2026 | Claude | Исправления по ревью 27.10.2026 (п. 2.1, 2.2, 2.4): воины не появляются из неизвестных и повторных походов, отправка с откатом, тесты крайних случаев боя. Обновлены Army, World, Battle, Core. |
| 27.10.2026 | Claude | Слой приложения: содержимое окон города (`BasePanel`) — в безопасной зоне, левый край больше не уходит под вырез камеры. `SafeArea.fitInsideParent` — для объектов не на весь экран. |
| 27.10.2026 | Claude | Гарнизон города в модуле Армии. Обновлены Army, Core, World. |
| 27.10.2026 | Claude | Лагеря разбойников (PvE) на карте мира. Обновлены World, Battle, Save, Core. |
| 27.10.2026 | Claude | Боевая система с типами войск (контры, стены, осадные, потери по типам), состав гарнизонов на карте, ожидаемый исход в окне атаки. Обновлены Battle, World, Army, Core. |
| 27.10.2026 | Claude | Свободная стройка на сетке: призрак здания, красные занятые клетки, разный размер зданий. Обновлён Settlement. |
| 27.10.2026 | Claude | Этапы 1 и 3: склады и лимиты, добыча через рабочих, окно здания и рабочих, улучшение зданий, Склад и Амбар. Тесты `ProductionTests`. Обновлены Economy, Population, Core, Save. |
| 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`. |