MVP1/Docs/Modules/README.md

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

Игра собрана из девяти модулей вокруг общего Игрового ядра. Модули общаются только через контракты и события ядра и не управляют внутренним кодом друг друга. Это правило проверяет сам 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
Экономика	Bogatyri.Economy	Assets/Scripts/Modules/Economy	Economy.md
Поселение	Bogatyri.Settlement	Assets/Scripts/Modules/Settlement	Settlement.md
Армия	Bogatyri.Army (без Unity)	Assets/Scripts/Modules/Army	Army.md
Население	Bogatyri.Population (без Unity)	Assets/Scripts/Modules/Population	Population.md
Глобальный мир	Bogatyri.World, Bogatyri.World.Simulation (без Unity)	Assets/Scripts/Modules/World	World.md
Боевая система	Bogatyri.Battle (без Unity)	Assets/Scripts/Modules/Battle	Battle.md
Сохранения	Bogatyri.Save	Assets/Scripts/Modules/Save	Save.md
Чат	Bogatyri.Chat (без Unity)	Assets/Scripts/Modules/Chat	Chat.md
Круг	Bogatyri.Circle (без Unity)	Assets/Scripts/Modules/Circle	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):

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

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

Дата	Кто	Что
27.10.2026	Claude	Гарнизон города в модуле Армии. Обновлены Army, Core, World.
27.10.2026	Claude	Лагеря разбойников (PvE) на карте мира. Обновлены World, Battle, Save, Core.
27.10.2026	Claude	Боевая система с типами войск (контры, стены, осадные, потери по типам), состав гарнизонов на карте, ожидаемый исход в окне атаки. Обновлены Battle, World, Army, Core.
26.10.2026	Claude	Модуль Населения (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): основать, вступить, выйти, роли, окно «Круг» на карте мира. Канал «Круг» в чате привязан к Кругу игрока.
19.10.2026	Claude	Добавлен модуль Чата (Bogatyri.Chat, 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.