Leonid Pershin
b318d1e795
CI / build-test (push) Failing after 1m13s
AtlasBuilder packs a directory tree of loose images into atlas pages plus JSON metadata (deterministic shelf packing, incremental rebuilds, orphan cleanup); TextureAtlas loads them back handing out Texture2DRegions, so sprites from one page batch into a single draw call. The asset handle generator maps .atlas files to TextureAtlas and skips page images. Demonstrated in the sample (Assets/Atlases + 'atlas' console command), wrapped as tools/MrGameEng.AtlasTool for build scripts. Documented dependency exception: Atlases depends on Graphics and Assets.
287 lines
22 KiB
Markdown
287 lines
22 KiB
Markdown
# Архитектура mrgameeng
|
||
|
||
## Обзор
|
||
|
||
**mrgameeng** — кроссплатформенный 2D игровой движок на базе MonoGame 3.8.4
|
||
(DesktopGL: Windows, Linux, macOS), .NET 8, C#.
|
||
|
||
Ключевое архитектурное решение — **ECS-first**: движок плотно интегрирует
|
||
[Friflo.Engine.ECS](https://github.com/friflo/Friflo.Engine.ECS) (v3.6) как ядро
|
||
модели объектов. Это самая производительная ECS-библиотека в .NET по результатам
|
||
[Ecs.CSharp.Benchmark](https://github.com/Doraku/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.UI` | Игровой UI на [Myra](https://github.com/rds1983/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.Assets.Generator` — особый случай: это анализатор (netstandard2.0),
|
||
он подключается к проекту игры как `Analyzer`, в рантайме не участвует и не зависит
|
||
от других модулей движка.
|
||
|
||
## Консоль разработчика
|
||
|
||
`MrGameEng.DevConsole` — ингейм-консоль (тогглинг клавишей <code>`</code>):
|
||
|
||
- Перехватывает всё, что пишется через статический `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](https://github.com/rds1983/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` игры).
|
||
По дереву папок он генерирует статический класс с типизированными хендлами,
|
||
тип выводится из расширения файла:
|
||
|
||
```csharp
|
||
// 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`.
|
||
|
||
## Рендеринг
|
||
|
||
`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 | Компиляция шейдеров при сборке |
|