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; остаются дебаффы производства и правило снятия — экономика;
• предел синих кристаллов: кристаллы не копятся бесконечно, сверх лимита — по общему правилу.

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

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