MVP1/Docs/Modules

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

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

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

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

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

Не путать:

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

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

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

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

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

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

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

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

Дата	Кто	Что
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), таблица баланса 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.