mrgameeng/docs/architecture.md

Архитектура mrgameeng

Обзор

mrgameeng — кроссплатформенный 2D игровой движок на базе MonoGame 3.8.4 (DesktopGL: Windows, Linux, macOS), .NET 8, C#.

Ключевое архитектурное решение — ECS-first: движок плотно интегрирует Friflo.Engine.ECS (v3.6) как ядро модели объектов. Это самая производительная ECS-библиотека в .NET по результатам Ecs.CSharp.Benchmark: ноль аллокаций в горячих путях, archetype-хранилище, встроенные системы, события и индексы.

Принципы

1. Данные отдельно от логики. Всё состояние игры — в компонентах (struct : IComponent), вся логика — в системах (QuerySystem<T>). Никаких Update() у игровых объектов и иерархий наследования сущностей.
2. Ноль аллокаций в кадре. Системы, выполняющиеся каждый кадр, не должны аллоцировать память. Проверяется бенчмарками и code review.
3. Модульность. Движок разбит на библиотеки по функциональным областям. Игра подключает только то, что использует.
4. Всё демонстрируется. Каждая публичная возможность движка показана в MrGameEng.Sample и покрыта тестами (где логика тестируема без GPU).

Модули

Библиотека	Ответственность
MrGameEng.Core	Игровой цикл (хост над Game), EntityStore, SystemRoot, сцены, время, жизненный цикл
MrGameEng.Graphics	Собственный батчер-рендерер (см. «Рендеринг»), камера, спрайты, анимации, слои
MrGameEng.Input	Абстракция ввода: клавиатура, мышь, геймпад; action maps
MrGameEng.Audio	Звуковые эффекты и музыка
MrGameEng.Assets	Runtime-загрузка ресурсов без Content Pipeline, кэш, AssetRef<T>
MrGameEng.Assets.Generator	Roslyn incremental source generator: классы с типизированными хендлами ресурсов
MrGameEng.Atlases	Текстурные атласы: офлайн-сборка из дерева картинок (AtlasBuilder) и рантайм-загрузка (TextureAtlas); CLI — tools/MrGameEng.AtlasTool
MrGameEng.Tilemaps	Тайловые карты, создаваемые кодом: TileGrid + TileSet + компонент Tilemap, отрисовка видимых клеток через батчер
MrGameEng.UI	Игровой UI на Myra: Desktop на сцену, виджеты, скининг
MrGameEng.DevConsole	Ингейм-консоль разработчика: логи Log, команды, история, автодополнение

Планируемые модули (по мере развития): Physics2D, Tilemap, UI, Particles.

Правило зависимостей

MrGameEng.Graphics ─┐
MrGameEng.Input    ─┤
MrGameEng.Audio    ─┼──► MrGameEng.Core ──► MonoGame.Framework.DesktopGL
MrGameEng.Assets   ─┘                  └──► Friflo.Engine.ECS

Модули зависят только от Core и никогда друг от друга. Core зависит только от MonoGame и Friflo. Если двум модулям нужен общий тип — он переезжает в Core.

Документированные исключения: MrGameEng.Atlases зависит от Graphics (выдаёт Texture2DRegion) и от Assets (регистрирует загрузчик в AssetManager) — атлас по своей природе склейка этих двух областей; MrGameEng.Tilemaps зависит от Graphics (рисует регионы через рендерер и слои).

MrGameEng.Assets.Generator — особый случай: это анализатор (netstandard2.0), он подключается к проекту игры как Analyzer, в рантайме не участвует и не зависит от других модулей движка.

Консоль разработчика

MrGameEng.DevConsole — ингейм-консоль (тогглинг клавишей `):

• Перехватывает всё, что пишется через статический MrGameEng.Core.Log (Debug/Info/Warning/Error; движок логирует ключевые события сам).
• Команды: console.Register(name, description, handler); встроенные — help, clear, echo, timescale, close, quit; игра добавляет свои.
• История ввода (↑/↓), автодополнение по Tab, скролл (PageUp/PageDown/End/колесо).
• Производительность: кольцевой буфер строк (2048), отрисовка — один Label, текст которого перестраивается только при изменении (Revision); при закрытой консоли — ноль работы в кадре.
• Ядро (DevConsole) — чистая логика без Myra, полностью покрыта headless-тестами; Myra-обвязка отдельно. scene.UseDevConsole() — последним в OnLoad, чтобы консоль рисовалась поверх UI. Сервис общий, живёт между сценами.

UI (Myra)

Игровой UI — интеграция Myra (выбор: экосистема FontStashSharp, не требует Content Pipeline, зрелая и поддерживаемая):

• scene.UseUI() в OnLoad после UseRenderer2D() — создаёт Myra Desktop (свой на сцену) и регистрирует UiRenderSystem последней в Draw-фазе.
• UI строится кодом через desktop.Root; ввод (мышь/клавиатура) Myra обрабатывает сама во время рендера, в оконных пикселях.
• Текст рисуется встроенным шрифтом Myra; свои шрифты — FontSystem через AssetManager.
• Документированное исключение из правил: Myra рисует собственным SpriteBatch (запрет на SpriteBatch относится к коду движка, не к сторонним библиотекам). Если UI станет узким местом, её рендер можно перевести на наш батчер через IMyraRenderer (бэклог).

Загрузка ресурсов (без Content Pipeline)

MGCB / Content Pipeline не используется. Все ресурсы лежат в папке Assets/ проекта игры как сырые файлы (копируются в output при сборке) и грузятся в рантайме:

Тип	Форматы	Как грузим
Текстуры	png, jpg	Texture2D.FromFile
Шрифты	ttf	FontStashSharp (растеризация в рантайме, динамический атлас)
Звуки	wav	SoundEffect.FromFile
Музыка	ogg	Стриминг через NVorbis + DynamicSoundEffectInstance
Шейдеры	fx	Компиляция dotnet-mgfxc на этапе сборки (MSBuild target), в рантайме грузится байткод .mgfx

AssetManager (в MrGameEng.Assets) грузит ресурсы по типизированному хендлу AssetRef<T> (путь + тип), кэширует по пути и владеет временем жизни (Dispose при выгрузке сцены/игры).

Кодогенератор хендлов

MrGameEng.Assets.Generator — Roslyn incremental source generator. Файлы из Assets/ передаются ему через AdditionalFiles (один glob в .csproj игры). По дереву папок он генерирует статический класс с типизированными хендлами, тип выводится из расширения файла:

// Assets/Textures/player.png  →
public static partial class GameAssets
{
    public static class Textures
    {
        public static readonly AssetRef<Texture2D> Player = new("Textures/player.png");
    }
}

// использование: Texture2D tex = assets.Load(GameAssets.Textures.Player);

Обращение к ресурсу по строковому пути в коде игры — запрещено соглашением; строки существуют только внутри сгенерированного кода.

Текстурные атласы

MrGameEng.Atlases превращает дерево отдельных картинок в атласы и грузит их в рантайме. Спрайты с регионами одной страницы атласа батчер сливает в один draw call.

Сборка (билд-тайм, без GPU)

AtlasBuilder.Build(AtlasBuildOptions) — чистый CPU (StbImageSharp/StbImageWriteSharp):

• Источник сканируется рекурсивно (png/jpg/jpeg/bmp); картинки группируются в атласы по первым GroupDepth папкам относительного пути (0 — один атлас на всё).
• Упаковка — детерминированный shelf-packer (ShelfPacker): сортировка по высоте, полки, страницы до MaxPageSize² (по умолчанию 2048), зазор Padding (2 px), размер страницы подрезается до степени двойки; негабаритные картинки получают отдельную страницу под себя.
• Выход: страницы <Имя>.atlas.<N>.png + метаданные <Имя>.atlas (JSON: страницы, регионы с ключами и прямоугольниками). Ключ региона — путь от корня источника без расширения (Things/Pawn/Animal/Fox).
• Инкрементальность: группа пересобирается только если изменились исходники, состав файлов или параметры сборки; атласы исчезнувших групп удаляются из выходной папки.

CLI-обёртка: dotnet run --project tools/MrGameEng.AtlasTool -- <источник> <выход> [--group-depth N] [--page-size N] [--padding N] [--root-name Имя] [--force].

Загрузка (рантайм)

• context.UseTextureAtlases() регистрирует загрузчик TextureAtlas в AssetManager; кодогенератор выдаёт хендлы AssetRef<TextureAtlas> для файлов .atlas (страницы *.atlas.N.png собственных Texture2D-хендлов не получают).
• TextureAtlas владеет страницами (premultiplied alpha, как все текстуры движка) и отдаёт регионы: atlas.GetRegion("Things/Pawn/Animal/Fox") → Texture2DRegion, готовый для Sprite.

Тайловые карты

MrGameEng.Tilemaps — тайловые карты, создаваемые кодом (загрузка Tiled — в бэклоге):

• TileSet — словарь тайлов: Add(region, tint?) возвращает id; id 0 зарезервирован под «пусто». Регион + тинт позволяют строить тайлсеты и из текстур атласа, и из тонированной белой текстуры.
• TileGrid — плотная сетка ushort-id с проверкой границ; заполняется генератором мира, мутируется в рантайме (изменение видно со следующего кадра).
• Компонент Tilemap (struct : IComponent): грид + тайлсет + Origin, TileSize, слой, Depth, общий тинт карты. Обычная сущность — карт может быть несколько (земля, декор поверх).
• scene.UseTilemaps() (после UseRenderer2D()) вставляет TilemapRenderSystem в Draw-фазу перед flush. Система считает видимый диапазон клеток по cull-rect камеры (TilemapMath.VisibleCells) и сабмитит только его: стоимость кадра зависит от экрана, а не от размера грида. Тайлы батчатся со спрайтами по обычному порядку слой → depth → текстура: пол из одной текстуры атласа — один draw call.

Рендеринг

SpriteBatch в движке не используется — в MrGameEng.Graphics свой батчер, спроектированный под ECS.

Камера

Ортографическая 2D-камера — из коробки, отдельная сущность с компонентом Camera:

• Позиция, зум, поворот, опциональные границы мира (clamp).
• Строит ортографическую view-projection матрицу; виртуальное разрешение с letterbox/scale под размер окна.
• Активная камера — одна на сцену. Утилиты ScreenToWorld / WorldToScreen.

Слои (render layers)

• Слои регистрируются явно при настройке рендерера: имя + порядок отрисовки (например, Background → World → Foreground → UI).
• У каждого слоя — пространство: World (через трансформ камеры) или Screen (screen-space, без камеры — HUD, UI).
• Сортировка внутри слоя — по float depth спрайта; слой можно переключить в режим Y-sort (depth = позиция Y, для top-down игр).
• Спрайт ссылается на слой компактным id (LayerId), не строкой.

Culling

• Перед записью вершин AABB спрайта (с учётом rotation/scale) проверяется против world-прямоугольника камеры; невидимые сущности не попадают в батчер.
• Screen-space слои не куллятся по камере (они всегда на экране).
• Culling — простой broad-phase в draw-системе, без пространственных структур; если профилирование покажет, что на больших мирах его не хватает, добавим spatial hash отдельным этапом.

Батчер

• Draw-системы итерируют чанки Friflo (Chunks<Position, Sprite, ...>) и пишут вершины напрямую в CPU-буфер батчера — без промежуточных списков и аллокаций.
• Порядок сортировки: слой → depth (или Y) → текстура; спрайты с одной текстурой сливаются в один draw call (динамический vertex buffer + общий quad index buffer).
• Сортировка — стабильный LSD radix sort: спрайты с равным ключом сохраняют порядок сабмита между кадрами (нет мерцания), сложность O(n); проходы по одинаковым у всех ключей разрядам пропускаются.
• Горячий путь без тригонометрии, корней и делений: для спрайтов без поворота SinCos не вычисляется; радиус culling-окружности и UV-координаты предрассчитаны в Texture2DRegion.
• Параллелизм: выше Renderer2DOptions.ParallelThreshold (по умолчанию 8192) подача спрайтов и построение вершин идут на всех ядрах. Работа режется на сегменты по 4096 сущностей (чанк Friflo держит весь архетип — сам по себе он слишком крупный для распределения); сегменты сливаются в детерминированном порядке, поэтому стабильность сортировки сохраняется. Ниже порога — прежний однопоточный путь без аллокаций.
• Vertex buffer пишется кольцом (SetDataOptions.NoOverwrite, GPU-буфер вдвое больше кадра): загрузка не ждёт, пока GPU дорисует предыдущий кадр; Discard — только на перемотке кольца.
• Тайминги фаз кадра (submit/sort/build/upload/draw, мс) доступны как свойства Renderer2D — выводятся в HUD стресс-сцены; оптимизации делаются только по ним.
• Текстурные атласы — первоклассный гражданин: Sprite хранит регион атласа, спрайты одного атласа батчатся автоматически.
• Цель по производительности: ≥100k спрайтов при 60 FPS на среднем десктопе, 0 аллокаций на кадр ниже порога параллелизма. Стресс-сцена Sample: 100k сущностей (~61k в кадре) ≈ 297 FPS в Release. Производительность измеряется только в Release — Debug-сборка медленнее в 5–6 раз (нет инлайнинга JIT).

Сцены и переходы

• SceneManager владеет активной сценой; обычное переключение откладывается до начала следующего кадра (сцена никогда не выгружается посреди собственного кадра).
• Scenes.Switch(scene, Transition.Fade(0.5f)) — переключение с визуальным переходом: фаза закрытия (старая сцена живёт) → своп при полном покрытии → фаза открытия. Тяжёлый OnLoad новой сцены скрыт за полностью закрытым экраном.
• Встроенные переходы: Transition.Fade(duration, color) и Transition.Wipe(duration, color) (шторка). Свои — наследованием от Transition (рисование через TransitionRenderer.Fill в нормализованных координатах экрана).
• Переходы идут по unscaled-времени: работают при паузе геймплея (TimeScale = 0).
• Повторный Switch во время перехода заменяет целевую сцену, не перезапуская переход.

Интеграция ECS

• На каждую сцену создаётся свой EntityStore (мир) и два SystemRoot: UpdateSystems (логика) и DrawSystems (рендер). Порядок систем детерминирован и задаётся явно при регистрации.
• Модули подключаются к сцене extension-методами из OnLoad: scene.UseRenderer2D(), scene.UseInput(), scene.UseSpriteAnimation(), context.UseAssets(), context.UseAudio(). Сервисы модулей живут в EngineContext.Services (общие между сценами), системы — в сцене.
• Базовый трансформ — один компонент Transform2D (position + rotation + scale): один массив на чанк дешевле трёх отдельных компонентов.
• Модули поставляют готовые компоненты и системы (например, Sprite + SpriteRenderSystem из Graphics), игра добавляет свои.

Кадр (frame pipeline)

Game.Update ──► Scene.Update ──► SystemRoot (Update-фаза): input → логика игры → анимации
Game.Draw  ──► Scene.Draw   ──► SystemRoot (Draw-фаза):  камера → culling → запись вершин в батчер → flush (draw calls)

Структура репозитория

MrGameEng.sln
src/        библиотеки движка (MrGameEng.*)
samples/    MrGameEng.Sample — демо всех возможностей
tests/      xUnit-тесты, по проекту на библиотеку
docs/       документация (русский)

Зафиксированные версии

Зависимость	Версия	Назначение
.NET (target framework)	net8.0
MonoGame.Framework.DesktopGL	3.8.4.1	Базовый фреймворк
Friflo.Engine.ECS	3.6.0	ECS
FontStashSharp.MonoGame	1.5.6	Шрифты (ttf) в рантайме
NVorbis	0.10.5	Декодирование ogg
Myra	1.6.1	Игровой UI
StbImageSharp	2.30.15	Декодирование картинок при сборке атласов
StbImageWriteSharp	1.16.7	Запись PNG-страниц атласов
dotnet-mgfxc (dotnet tool)	3.8.4.1	Компиляция шейдеров при сборке