MVP1/Docs/Modules

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

Игра собрана из десяти модулей вокруг общего Игрового ядра (регламент 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
Экономика	Bogatyri.Economy, Bogatyri.Economy.Rules (без Unity)	Assets/Scripts/Modules/Economy	Economy.md
Поселение	Bogatyri.Settlement	Assets/Scripts/Modules/Settlement	Settlement.md
Население	Bogatyri.Population (без Unity)	Assets/Scripts/Modules/Population	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
Разведка	Bogatyri.Intelligence (без Unity)	Assets/Scripts/Modules/Intelligence	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):

• лимит жилья: 300 жителей при лимите 300 — прирост стоит, предел вырос — прирост идёт (PopulationTests; пока предел растёт от Ратуши, Дома ещё нет);
• нельзя призвать ниже гражданского резерва: 150 свободных, резерв 30 → призвать можно не больше 120; резерв по уровню Ратуши 10/20/30 (PopulationTests);
• назначение гарнизона: 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 (Валдемар)	Решения Димы 04.11: снос зданий убран (только бесплатный перенос), кристаллы грабятся только с технологией «Грабёж», офлайн по временным меткам — добыча с момента завершения стройки, защита от повторного начисления (метка расчёта не уходит назад). +5 тестов. Обновлены Settlement, Economy, Core.
04.11.2026	Claude	Разведка М2: разведка поселений, замка и лагерей с отчётами II и III. Обновлены Intelligence, World, Core.
04.11.2026	Claude	Пропавшие без вести (решения 01.11, п. 5; доля не утверждена — выключено). Обновлены Army, Battle, Population, World, Core.
04.11.2026	Claude	Еда воинов и раненых по типам (решения 01.11, п. 4). Обновлены Population, Army.
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 (Валдемар)	Поселение: стройка и улучшение по времени, 2 строителя, ускорение; лимит зданий по Ратуше; перенос и снос; защита ресурсов от грабежа (IResourceProtection). Терем богатыря и герой в городе. Казармы: найм карточками в ряд. Числа — ТЕСТ. Обновлены Settlement, Economy, Core.
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): туман, обзор, чужие армии, последний контакт. Патрули-заглушки соседей для проверки. Обновлены 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), таблица баланса 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.