# DragonECS - C# Entity Component System Фреймворк

Readme Languages:
Русский	English	中文

DragonECS - это [ECS](https://en.wikipedia.org/wiki/Entity_component_system) фреймворк нацеленный на максимальную удобность, модульность, расширяемость и производительность динамического изменения сущностей. Разработан на чистом C#, без зависимостей и генерации кода. Вдохновлен [LeoEcs Lite](https://github.com/Leopotam/ecslite). > [!WARNING] > Проект предрелизной версии, поэтому API может меняться. В ветке main актуальная и рабочая версия. > > Если есть неясные моменты, вопросы можно задать тут [Обратная связь](#обратная-связь) ## Оглавление - [Установка](#установка) - [Расширения](#расширения) - [Основные концепции](#основные-концепции) - [Entity](#entity) - [Component](#component) - [System](#system) - [Концепции фреймворка](#концепции-фреймворка) - [Пайплайн](#пайплайн) - [Построение](#построение) - [Внедрение зависимостей](#внедрение-зависимостей) - [Модули](#модули) - [Сортировка](#сортировка) - [Процессы](#процессы) - [Мир](#мир) - [Пул](#пул) - [Маска](#маска) - [Аспект](#аспект) - [Запросы](#запросы) - [Коллекции](#Коллекции) - [Корень ECS](#корень-ecs) - [Debug](#debug) - [Мета-Атрибуты](#мета-атрибуты) - [EcsDebug](#ecsdebug) - [Профилирование](#профилирование) - [Define Symbols](#define-symbols) - [Расширение фреймворка](#расширение-фреймворка) - [Компоненты мира](#компоненты-мира) - [Конфиги](#конфиги) - [Проекты на DragonECS](#Проекты-на-DragonECS) - [FAQ](#faq) - [Обратная связь](#обратная-связь)
# Установка Семантика версионирования - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md) ## Окружение Обязательные требования: + Минимальная версия C# 7.3; Поддерживает: + NativeAOT; + Игровые движки с C#: Unity, Godot, MonoGame и т.д. Протестировано: + **Unity:** Минимальная версия 2021.2.0; ## Установка для Unity > Рекомендуется так же установить расширение [Интеграция с движком Unity](https://github.com/DCFApixels/DragonECS-Unity) * ### Unity-модуль Поддерживается установка в виде Unity-модуля при помощи добавления git-URL [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html): ``` https://github.com/DCFApixels/DragonECS.git ``` Или ручного добавления этой строчки в `Packages/manifest.json`: ``` "com.dcfa_pixels.dragonecs": "https://github.com/DCFApixels/DragonECS.git", ``` * ### В виде исходников Можно так же напрямую скопировать в проект исходники фреймворка.
# Расширения * Интеграции: * [Unity](https://github.com/DCFApixels/DragonECS-Unity) * [Godot](https://gitlab.com/InauniusOwn/Libraries/DraGodot) * Пакеты: * [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections) * [Классическая C# многопоточность](https://github.com/DCFApixels/DragonECS-ClassicThreads) * [Recursivity](https://github.com/DCFApixels/DragonECS-Recursivity) * [Hybrid](https://github.com/DCFApixels/DragonECS-Hybrid) * [Графы](https://github.com/DCFApixels/DragonECS-Graphs) * Утилиты: * [Упрощенный синтаксис](https://gist.github.com/DCFApixels/d7bfbfb8cb70d141deff00be24f28ff0) * [EcsRefPool](https://gist.github.com/DCFApixels/73e392ccabdd98b3d4a517017d8a3f22) * [Таймеры](https://gist.github.com/DCFApixels/71a416275660c465ece76242290400df) * [Однокадровые компоненты](https://gist.github.com/DCFApixels/46d512dbcf96c115b94c3af502461f60) * [Шаблоны кода IDE](https://gist.github.com/ctzcs/0ba948b0e53aa41fe1c87796a401660b) и [для Unity](https://gist.github.com/ctzcs/d4c7730cf6cd984fe6f9e0e3f108a0f1) > *Твое расширение? Если разрабатываешь расширение для DragonECS, пиши [сюда](#обратная-связь).
# Основные концепции ## Entity **Сущности** - это то к чему крепятся данные. Для доступа к сущности используются идентификаторы двух типов: * `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется использовать для хранения; * `entlong` - долговременный идентификатор, содержит метку поколения, что делает его уникальным навсегда. Подходит для хранения. ``` c# // Создание новой сущности в мире. int entityID = _world.NewEntity(); // Удаление сущности. _world.DelEntity(entityID); // Копирование компонентов одной сущности в другую. _world.CopyEntity(entityID, otherEntityID); // Клонирование сущности. int newEntityID = _world.CloneEntity(entityID); ```

Работа с entlong

``` c# // Конвертация int в entlong. entlong entity = _world.GetEntityLong(entityID); // упрощенная версия entlong entity = (_world, entityID); // Проверка что сущность еще жива. if (entity.IsAlive) { } // Конвертация entlong в int. Если сущность уже не существует, будет брошено исключение. int entityID = entity.ID; // или var (entityID, world) = entity; // Конвертация entlong в int. Вернет true и ее int идентификатор, если сущность еще жива. if (entity.TryGetID(out int entityID)) { } ```

> > Сущности не могут существовать без компонентов, пустые сущности будут автоматически удаляться сразу после удаления последнего компонента либо в конце тика. ## Component **Компоненты** - это данные которые крепятся к сущностям. ```c# // Компоненты IEcsComponent хранятся в обычном хранилище. struct Health : IEcsComponent { public float health; public int armor; } // Компоненты с IEcsTagComponent хранятся в оптимизированном для тегов хранилище. struct PlayerTag : IEcsTagComponent {} ``` ## System **Системы** - это основная логика, тут задается поведение сущностей. Существуют в виде пользовательских классов, реализующих как минимум один из интерфейсов процессов. Основные процессы: ```c# class SomeSystem : IEcsPreInit, IEcsInit, IEcsRun, IEcsDestroy { // Будет вызван один раз в момент работы EcsPipeline.Init() и до срабатывания IEcsInit.Init(). public void PreInit () { } // Будет вызван один раз в момент работы EcsPipeline.Init() и после срабатывания IEcsPreInit.PreInit(). public void Init () { } // Будет вызван один раз в момент работы EcsPipeline.Run(). public void Run () { } // Будет вызван один раз в момент работы EcsPipeline.Destroy(). public void Destroy () { } } ``` > Для реализации дополнительных процессов перейдите к разделу [Процессы](#Процессы).

Пример системы

``` c# // Система class DamageSystem : IEcsRun, IEcsInject { // Аспекты описаны в соответствующей главе class Aspect : EcsAspect { public EcsPool DamageRequests = Inc; public EcsPool Healths = Inc; } // Мир - хранилище сущностей, так же описан в соответствующей главе EcsDefaultWorld world; // Процесс Run public void Run() { // Итерируемся по сущностям, в рамках Run можно использовать int идентификаторы сущностей foreach (int e in world.Where(out Aspect a)) { // Логика нанесения урона a.Healths[e].Points -= a.DamageRequests[e].Points; } } // Процесс Inject. Получение инстанса EcsDefaultWorld void IEcsInject.Inject(EcsDefaultWorld obj) => world = obj; } // Компоненты public struct DamageRequest : IEcsComponent { public float Points; } public struct Health : IEcsComponent { public float Points; } ```

# Концепции фреймворка ## Пайплайн Контейнер и движок систем. Отвечает за настройку очереди вызова систем, предоставляет механизм для сообщений между системами и механизм внедрения зависимостей. Реализован в виде класса `EcsPipeline`. ### Построение За построение пайплайна отвечает Builder. В Builder добавляются системы, а в конце строится пайплайн. Пример: ```c# EcsPipeline pipeline = EcsPipeline.New() // Создает Builder пайплайна. // Добавляет систему System1 в очередь систем. .Add(new System1()) // Добавляет System2 в очередь после System1. .Add(new System2()) // Добавляет System3 в очередь после System2, но в единичном экземпляре. .AddUnique(new System3()) // Завершает построение пайплайна и возвращает его экземпляр. .Build(); pipeline.Init(); // Инициализация пайплайна. ``` ```c# class SomeSystem : IEcsRun, IEcsPipelineMember { // Получить экземпляр пайплайна к которому принадлежит система. public EcsPipeline Pipeline { get ; set; } public void Run () { } } ``` > Для одновременного построения и инициализации есть метод Builder.BuildAndInit(); ### Внедрение зависимостей Фреймворк реализует внедрение зависимостей для систем. это процесс который запускается вместе с инициализацией пайплайна и внедряет данные переданные в Builder. ``` c# class SomeDataA { /* ... */ } class SomeDataB : SomeDataA { /* ... */ } // ... SomeDataB _someDataB = new SomeDataB(); EcsPipeline pipeline = EcsPipeline.New() // ... // Внедрит _someDataB в системы реализующие IEcsInject. .Inject(_someDataB) // Добавит системы реализующие IEcsInject в дерево инъекции, // теперь эти системы так же получат _someDataB. .Injector.AddNode() // ... .Add(new SomeSystem()) // ... .BuildAndInit(); // ... // Для внедрения используется интерфейс IEcsInject и его метод Inject(T obj) class SomeSystem : IEcsInject, IEcsRun { SomeDataA _someDataA // obj будет экземпляром типа SomeDataB. public void Inject(SomeDataA obj) => _someDataA = obj; public void Run () { _someDataA.DoSomething(); } } ``` > Использование встроенного внедрения зависимостей опционально. > Имеется [Расширение](#расширения) упрощающее синтаксис инъекций - [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections). ### Модули Группы систем реализующие общую фичу можно объединять в модули, и просто добавлять модули в Pipeline. ``` c# using DCFApixels.DragonECS; class Module1 : IEcsModule { public void Import(EcsPipeline.Builder b) { b.Add(new System1()); b.Add(new System2()); b.AddModule(new Module2()); // ... } } ``` ``` c# EcsPipeline pipeline = EcsPipeline.New() // ... .AddModule(new Module1()) // ... .BuildAndInit(); ``` ### Сортировка Дла управления расположением систем в пайплайне, вне зависимости от порядка добавления, есть 2 способа: Слои и Порядок сортировки. #### Слои Слой определяет место в пайплайне для вставки систем. Например, если необходимо чтобы система была вставлена в конце пайплайна, эту систему можно добавить в слой `EcsConsts.END_LAYER`. ``` c# const string SOME_LAYER = nameof(SOME_LAYER); EcsPipeline pipeline = EcsPipeline.New() // ... // Вставляет новый слой перед конечным слоем EcsConsts.END_LAYER .Layers.Insert(EcsConsts.END_LAYER, SOME_LAYER) // Система SomeSystem будет вставлена в слой SOME_LAYER .Add(New SomeSystem(), SOME_LAYER) // ... .BuildAndInit(); ``` Встроенные слои расположены в следующем порядке: * `EcsConst.PRE_BEGIN_LAYER` * `EcsConst.BEGIN_LAYER` * `EcsConst.BASIC_LAYER` (По умолчанию системы добавляются сюда) * `EcsConst.END_LAYER` * `EcsConst.POST_END_LAYER` #### Порядок сортировки Для сортировки систем в рамках слоя используется int значение порядка сортировки. По умолчанию системы добавляются с `sortOrder = 0`. ``` c# EcsPipeline pipeline = EcsPipeline.New() // ... // Система SomeSystem будет вставлена в слой EcsConsts.BEGIN_LAYER // и расположена после систем с sortOrder меньше 10. .Add(New SomeSystem(), EcsConsts.BEGIN_LAYER, 10) // ... .BuildAndInit(); ``` ## Процессы Процессы - это очереди систем реализующие общий интерфейс, например `IEcsRun`. Для запуска процессов используются Runner-ы. Встроенные процессы запускаются автоматически. Есть возможность реализации пользовательских процессов.

Встроенные процессы

* `IEcsPreInit`, `IEcsInit`, `IEcsRun`, `IEcsDestroy` - процессы жизненного цикла `EcsPipeline`. * `IEcsInject` - Процессы системы [внедрения зависимостей](#Внедрение-зависимостей). * `IOnInitInjectionComplete` - Так же процесс системы [внедрения зависимостей](#Внедрение-зависимостей), но сигнализирует о завершении инициализирующей инъекции.

Пользовательские процессы

Для добавления нового процесса создайте интерфейс наследованный от `IEcsProcess` и создайте раннер для него. Раннер это класс реализующий интерфейс запускаемого процесса и наследуемый от `EcsRunner`. Пример: ``` c# // Интерфейс процесса. interface IDoSomethingProcess : IEcsProcess { void Do(); } ``` ``` c# // Реализация раннера. Пример реализации можно так же посмотреть в встроенном процессе IEcsRun sealed class DoSomethingProcessRunner : EcsRunner, IDoSomethingProcess { public void Do() { foreach (var item in Process) item.Do(); } } ``` ``` c# // Добавление раннера при создании пайплайна. _pipeline = EcsPipeline.New() // ... .AddRunner() // ... .BuildAndInit(); // Запуск раннера если раннер был добавлен. _pipeline.GetRunner.Do() // Или если раннер не был добавлен(Вызов GetRunnerInstance так же добавит раннер в пайплайн). _pipeline.GetRunnerInstance.Do() ```

Расширенная реализация раннера

``` c# internal sealed class DoSomethingProcessRunner : EcsRunner, IDoSomethingProcess { // RunHelper упрощает реализацию по подобию реализации встроенных процессов. // Автоматически вызывает маркер профайлера, а так же содержит try catch блок. private RunHelper _helper; protected override void OnSetup() { // Вторым аргументом задается имя маркера, если не указать, то имя будет выбрано автоматически. _helper = new RunHelper(this, nameof(Do)); } public void Do() { _helper.Run(p => p.Do()); } } ```

> Требования реализации раннеров: > * Наследоваться от `EcsRunner` можно только напрямую; > * Раннер может содержать только один интерфейс(за исключением `IEcsProcess`); > * Наследуемый класс `EcsRunner`, должен так же реализовать интерфейс `T`; > Не рекомендуется в цикле вызывать `GetRunner`, иначе кешируйте полученный раннер.

## Мир Контейнер для сущностей и компонентов. ``` c# // Создание экземпляра мира. _world = new EcsDefaultWorld(); // Создание и удаление сущности по примеру из раздела Сущности. var e = _world.NewEntity(); _world.DelEntity(e); // Уничтожение мира и освобождение ресурсов. Обязательно вызывать, иначе он будет висеть в памяти. _world.Destroy(); ``` > Миры изолированы друг от друга и могут обрабатываться в отдельных потоках. Но мультипоточная обработка одного мира поддерживается только при отсутствии добавления/удаления компонентов у сущностей. Для инициализации мира сразу необходимого размера и сокращения времени прогрева, в конструктор можно передать экземпляр `EcsWorldConfig`. ``` c# EcsWorldConfig config = new EcsWorldConfig( // Предварительно инициализирует вместимость мира для 2000 сущностей. entitiesCapacity: 2000, // Предварительно инициализирует вместимость пулов для 2000 компонентов. poolComponentsCapacity: 2000 // ... Есть и другие параметры ); _world = new EcsDefaultWorld(config); ``` ## Пул Хранилище для компонентов, пул предоставляет методы для добавления/чтения/редактирования/удаления компонентов на сущности. Есть несколько видов пулов, для разных видов компонентов: * `EcsPool` - универсальный пул, хранит struct-компоненты реализующие интерфейс `IEcsComponent`; * `EcsTagPool` - специальный пул, оптимизированный под компоненты-теги, хранит struct-компоненты с `IEcsTagComponent`; Пулы имеют 5 основных метода и их разновидности: ``` c# // Один из способов получить пул из мира. EcsPool poses = _world.GetPool(); // Добавит компонент на сущность, бросит исключение если компонент уже есть у сущности. ref var addedPose = ref poses.Add(entityID); // Вернет компонент, бросит исключение если у сущности нет этого компонента. ref var gettedPose = ref poses.Get(entityID); // Вернет компонент доступный только для чтения, бросит исключение если у сущности нет этого компонента. ref readonly var readonlyPose = ref poses.Read(entityID); // Вернет true если у сущности есть компонент, в противном случае false. if (poses.Has(entityID)) { /* ... */ } // Удалит компонент у сущности, бросит исключение если у сущности нет этого компонента. poses.Del(entityID); ``` > [!WARNING] > В `Release` сборке отключаются проверки на исключения. > Есть "безопасные" методы, которые сначала выполнят проверку наличия/отсутствия компонента, названия таких методов начинаются с `Try`.

Пользовательские пулы

Пулом выступает любой тип реализующий интерфейс `IEcsPoolImplementation` и имеющий конструктор без параметров. Ключевые моменты при реализации пула: * За примером реализации пула можно обратиться к реализации встроенного пула `EcsPool`. * Интерфейс `IEcsPoolImplementation` и его члены не предназначены для публичного использования, члены интерфейса рекомендуется реализовывать явно. * Подставленный в интерфейсе `IEcsPoolImplementation` тип `T` и тип возвращаемый в свойствах `ComponentType` с `ComponentTypeID` должны совпадать. * Обязательно регистрировать все изменения пула в экземпляре `EcsWorld.PoolsMediator` передаваемом в методе `OnInit`. * `EcsWorld.PoolsMediator` предназначен только для использования внутри пула. * Дефайн `DISABLE_POOLS_EVENTS` отключает реализуемые методы `AddListener` и `RemoveListener`. * В статическом классе `EcsPoolThrowHelper` определены бросания наиболее распространенных видов исключений. * В методе `OnReleaseDelEntityBuffer` происходит очистка удаленных сущностей. * Рекомендуется определить интерфейс которым обозначаются компоненты для нового пула. На основе этого интерфейса можно реализовать методы расширения вроде `GetPool()` для упрощенного доступа к пулам. * Пулы должны реализовывать блокировку. Блокировка пула работает только в `Debug` режиме, и должна бросать исключения при попытке добавления или удаления компонента.

## Маска Набор требований к компонентам сущности: какие компоненты должны присутствовать, а какие отсутствовать. Маска — это просто данные, она не выполняет поиск, а используется запросами для фильтрации сущностей. Обычно маски не используются в чистом виде, а являются частью [Аспекта](#Аспект). ``` c# // Создание маски с улосвием наличия компонентов SomeCmp1 и SomeCmp2, // и с улосвием отсутсвия компонента SomeCmp3. EcsMask mask = EcsMask.New(_world) // Inc - Условие наличия компонента. .Inc() .Inc() // Exc - Условие отсутствия компонента. .Exc() .Build(); ```

Статическая маска

`EcsMask` привязаны к конкретным экземплярам мира которые необходимо передавать в `EcsMask.New(world)`, но есть `EcsStaticMask` которую можно создать без привязки к миру. ``` c# class SomeSystem : IEcsRun { // EcsStaticMask можно создавать в статических полях. static readonly EcsStaticMask _staticMask = EcsStaticMask.Inc().Inc().Exc().Build(); // ... } ``` ``` c# // Конвертация в обычную маску. EcsMask mask = _staticMask.ToMask(_world); ```

## Аспект Пользовательские классы наследуемые от `EcsAspect`, описывающие наборы компонентов, с которыми работает система. Аспект одновременно выполняет две функции: + Маска — инициализирует и хранит [маску](#Маска), за счет чего может использоваться в запросах. + Кэш пулов — предоставляет быстрый доступ к пулам компонентов. Проще говоря, аспект — это удобный способ описать "с какими сущностями я работаю и как получать их компоненты". Пример: ``` c# class Aspect : EcsAspect { // Кешируется пул и тип Pose добавляется во включающее условие. public EcsPool poses = Inc; // Кешируется пул и тип Velocity добавляется во включающее условие. public EcsPool velocities = Inc; // Кешируется пул и тип FreezedTag добавляется в исключающее условие. public EcsTagPool freezedTags = Exc; } ``` Назначение статических свойств: + Inc — компонент должен быть у сущности (включающее условие) + кеширует пул + Exc — компонента не должно быть у сущности (исключающее условие) + кеширует пул + Opt — компонент может быть, но не влияет на фильтрацию (только кеширует пул для доступа) + Any — хотя бы один из компонентов с Any должен присутствовать + кеширует пул

Инициализация через метод (результат идентичен примеру выше):

``` c# class Aspect : EcsAspect { public EcsPool poses; public EcsPool velocities; protected override void Init(Builder b) { poses = b.IncludePool(); velocities = b.IncludePool(); b.ExcludePool(); } } ```

Комбинирование аспектов

В аспекты можно добавлять другие аспекты, тем самым комбинируя их. Маски так же будут скомбинированы. ``` c# class Aspect : EcsAspect { public OtherAspect1 otherAspect1; public OtherAspect2 otherAspect2; public EcsPool poses; protected override void Init(Builder b) { // Комбинирует с SomeAspect1. otherAspect1 = b.Combine(1); // Хотя для OtherAspect1 метод Combine был вызван раньше, сначала будет скомбинирован с OtherAspect2, так как по умолчанию order = 0. otherAspect2 = b.Combine(); // Если в OtherAspect1 или в OtherAspect2 было условие b.Exclude() тут оно будет заменено на b.Include(). poses = b.Include(); } } ``` Если будут конфликтующие ограничения у комбинируемых аспектов, то новые ограничения будут заменять добавленные ранее. Ограничения корневого аспекта всегда заменяют ограничения из добавленных аспектов. Визуальный пример комбинации ограничений: | | cmp1 | cmp2 | cmp3 | cmp4 | cmp5 | разрешение конфликтных ограничений| | :--- | :--- | :--- | :--- | :--- | :--- |:--- | | OtherAspect2 | :heavy_check_mark: | :x: | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: | | | OtherAspect1 | :heavy_minus_sign: | :heavy_check_mark: | :heavy_minus_sign: | :x: | :heavy_minus_sign: | Для `cmp2` будет выбрано :heavy_check_mark: | | Aspect | :x: | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_minus_sign: | :heavy_check_mark: | Для `cmp1` будет выбрано :x: | | Итоговые ограничения | :x: | :heavy_check_mark: | :heavy_minus_sign: | :x: | :heavy_check_mark: | |

## Запросы Запросы позволяют отфильтровать и получать коллекции сущностей, удовлетворяющих заданным условиям. Основной метод — `Where`, который фильтрует по маске компонентов и имеет несколько перегрузок: + `EcsWorld.Where(out TAspect aspect)` - Фильтрация по маске, определённой в аспекте, плюс получение самого аспекта с закешированными пулами. + `EcsWorld.Where(EcsMask mask)` - Обычная фильтрация по маске; `Where` можно вызывать не только у мира, но и у любых коллекций фреймворка (в этом плане Where чем-то похож на аналогичный из Linq). Также доступны перегрузки для сортировки сущностей с помощью `Comparison`. Пример системы: ``` c# public class SomeDamageSystem : IEcsRun, IEcsInject { class Aspect : EcsAspect { public EcsPool healths = Inc; public EcsPool damageSignals = Inc; public EcsTagPool isInvulnerables = Exc; // Наличие или отсутствие этого компонента не проверяется. public EcsTagPool isDiedSignals = Opt; } EcsDefaultWorld _world; public void Run() { // Запрашиваем сущности удовлетворяющее маске из Aspect foreach (var e in _world.Where(out Aspect a)) { // Сюда попадают сущности с компонентами Health, DamageSignal и без IsInvulnerable. ref var health = ref a.healths.Get(e); if(health.points > 0) { health.points -= a.damageSignals.Get(e).points; if(health.points <= 0) { // Создаем сигнал другим системам о том что сущность умерла. a.isDiedSignals.TryAdd(e); } } } } public void Inject(EcsDefaultWorld world) => _world = world; } ``` > Имеется [Расширение](#расширения) упрощающее синтаксис запросов и обращения к компонентам - [Упрощенный синтаксис](https://github.com/DCFApixels/DragonECS-AutoInjections). ## Коллекции ### EcsSpan `ref struct` коллекция сущностей, доступная только для чтения. Состоит из ссылки на массив, длинны и идентификатора мира. Аналог `ReadOnlySpan`. ``` c# // Запрос Where возвращает сущности в виде EcsSpan. EcsSpan es = _world.Where(out Aspect a); // Итерироваться можно по foreach и for. foreach (var e in es) { // ... } for (int i = 0; i < es.Count; i++) { int e = es[i]; // ... } ``` > Хотя `EcsSpan` является просто массивом, в нем не допускается дублирование сущностей. ### EcsGroup Вспомогательная коллекция основанная на Sparse Set для хранения множества сущностей с `O(1)` операциями добавления/удаления/проверки и т.д. ``` c# // Получаем новую группу. EcsWorld содержит в себе пул групп, // поэтому будет переиспользована свободная или создана новая. EcsGroup group = EcsGroup.New(_world); // Освобождаем группу. group.Dispose(); ``` ``` c# // Добавляем сущность entityID. group.Add(entityID); // Проверяем наличие сущности entityID. group.Has(entityID); // Удаляем сущность entityID. group.Remove(entityID); ``` ``` c# // Запрос WhereToGroup возвращает сущности в виде группы только для чтения EcsReadonlyGroup. EcsReadonlyGroup group = _world.WhereToGroup(out Aspect a); // Итерироваться можно по foreach и for. foreach (var e in group) { // ... } for (int i = 0; i < group.Count; i++) { int e = group[i]; // ... } ``` Группы являются множествами и реализуют интерфейс `ISet`. Редактирующие методы имеет 2 варианта, с записью результата в groupA, либо с возвращением новой группы. ``` c# // Объединение groupA и groupB. groupA.UnionWith(groupB); EcsGroup newGroup = EcsGroup.Union(groupA, groupB); // Пересечение groupA и groupB. groupA.IntersectWith(groupB); EcsGroup newGroup = EcsGroup.Intersect(groupA, groupB); // Разность groupA и groupB. groupA.ExceptWith(groupB); EcsGroup newGroup = EcsGroup.Except(groupA, groupB); // Симметрическая разность groupA и groupB. groupA.SymmetricExceptWith(groupB); EcsGroup newGroup = EcsGroup.SymmetricExcept(groupA, groupB); // Разница всех сущностей в мире и groupA. groupA.Inverse(); EcsGroup newGroup = EcsGroup.Inverse(groupA); ``` ## Корень ECS Это пользовательский класс который является точкой входа для ECS. Основное назначение инициализация, запуск систем на каждый Update движка и освобождение ресурсов по окончанию использования. ### Пример для Unity ``` c# using DCFApixels.DragonECS; using UnityEngine; public class EcsRoot : MonoBehaviour { private EcsPipeline _pipeline; private EcsDefaultWorld _world; private void Start() { // Создание мира для сущностей и компонентов. _world = new EcsDefaultWorld(); // Создание пайплайна для систем. _pipeline = EcsPipeline.New() // Добавление систем. // .Add(new SomeSystem1()) // .Add(new SomeSystem2()) // .Add(new SomeSystem3()) // Внедрение мира в системы. .Inject(_world) // Прочие внедрения. // .Inject(SomeData) // Завершение построения пайплайна. .Build(); // Инициализация пайплайна и запуск IEcsPreInit.PreInit() // и IEcsInit.Init() у всех добавленных систем. _pipeline.Init(); } private void Update() { // Запуск IEcsRun.Run() у всех добавленных систем. _pipeline.Run(); } private void OnDestroy() { // Запускает IEcsDestroy.Destroy() у всех добавленных систем. _pipeline.Destroy(); _pipeline = null; // Обязательно удалять миры которые больше не будут использованы. _world.Destroy(); _world = null; } } ``` ### Общий пример ``` c# using DCFApixels.DragonECS; public class EcsRoot { private EcsPipeline _pipeline; private EcsDefaultWorld _world; // Инициализация окружения. public void Init() { //Создание мира для сущностей и компонентов. _world = new EcsDefaultWorld(); //Создание пайплайна для систем. _pipeline = EcsPipeline.New() // Добавление систем. // .Add(new SomeSystem1()) // .Add(new SomeSystem2()) // .Add(new SomeSystem3()) // Внедрение мира в системы. .Inject(_world) // Прочие внедрения. // .Inject(SomeData) // Завершение построения пайплайна. .Build(); // Инициализация пайплайна и запуск IEcsPreInit.PreInit() // и IEcsInit.Init() у всех добавленных систем. _pipeline.Init(); } // Update-цикл движка. public void Update() { // Запуск IEcsRun.Run() у всех добавленных систем. _pipeline.Run(); } // Очистка окружения. public void Destroy() { // Запускает IEcsDestroy.Destroy() у всех добавленных систем. _pipeline.Destroy(); _pipeline = null; // Обязательно удалять миры которые больше не будут использованы. _world.Destroy(); _world = null; } } ```
# Debug Фреймворк предоставляет дополнительные инструменты для отладки и логирования, не зависящие от среды. Так же многие типы имеют свой DebuggerProxy для более информативного отображения в IDE. ## Мета-Атрибуты По умолчанию мета-атрибуты не имеют применения, но используются в интеграциях с движками для задания отображения в отладочных инструментах и редакторах. А так же могут быть использованы для генерации автоматической документации. ``` c# using DCFApixels.DragonECS; // Задает пользовательское название типа, по умолчанию используется имя типа. [MetaName("SomeComponent")] // Используется для группировки типов. [MetaGroup("Abilities", "Passive", ...)] // или [MetaGroup("Abilities/Passive/")] // Задает цвет типа в RGB кодировке, где каждый канал принимает значение от 0 до 255, по умолчанию белый. [MetaColor(MetaColor.Red)] // или [MetaColor(255, 0, 0)] // Добавляет описание типу. [MetaDescription("The quick brown fox jumps over the lazy dog")] // Добавляет строковый уникальный идентификатор. [MetaID("8D56F0949201D0C84465B7A6C586DCD6")] // Строки должны быть уникальными, и не допускают символы ,<> . // Добавляет строковые теги. [MetaTags("Tag1", "Tag2", ...)] // [MetaTags(MetaTags.HIDDEN))] чтобы скрыть в редакторе public struct Component : IEcsComponent { /* ... */ } ``` ``` c# // Получение мета-информации: TypeMeta typeMeta = someComponent.GetMeta(); // или TypeMeta typeMeta = pool.ComponentType.ToMeta(); var name = typeMeta.Name; // [MetaName] var group = typeMeta.Group; // [MetaGroup] var color = typeMeta.Color; // [MetaColor] var description = typeMeta.Description; // [MetaDescription] var metaID = typeMeta.MetaID; // [MetaID] var tags = typeMeta.Tags; // [MetaTags] ``` > Для автоматической генерации уникальных идентификаторов MetaID есть метод `MetaID.GenerateNewUniqueID()` и [Браузерный генератор](https://dcfapixels.github.io/DragonECS-MetaID_Generator_Online/) ## EcsDebug Вспомогательный тип с набором методов для отладки и логирования. Реализован как статический класс вызывающий методы Debug-сервисов. Debug-сервисы - это посредники между EcsDebug и инструментами отладки среды. Такая реализация позволяет не изменяя отладочный код, менять его поведение или переносить проект в другие среды, достаточно только реализовать соответствующий Debug-сервис. ``` c# // Вывод лога. EcsDebug.Print("Message"); // Вывод лога с тегом. EcsDebug.Print("Tag", "Message"); // Прерывание игры. EcsDebug.Break(); // Установка другого Debug-Сервиса. EcsDebug.Set(); ``` > По умолчанию используется `DefaultDebugService` который выводит логи в консоль. Для реализации пользовательского создайте класс наследуемый от `DebugService` и реализуйте абстрактные члены класса. > `EcsDebug` потокобезопасен, за счет того что каждый поток использует свой изолированный экземпляр сервиса. Экземпляры для потоков создаются в абстрактном методе `DebugService.CreateThreadInstance`. ## Профилирование За реализацию профайлера так же отвечает Debug-сервис. Для выделения участка кода используется `EcsProfilerMarker`; ``` c# // Создание маркера с именем SomeMarker. private static readonly EcsProfilerMarker _marker = new EcsProfilerMarker("SomeMarker"); ``` ``` c# _marker.Begin(); // Код для которого замеряется скорость. _marker.End(); // или using (_marker.Auto()) { // Код для которого замеряется скорость. } ``` > `DefaultDebugService` использует реализацию на основе `Stopwatch` и выводом в консоль.
# Define Symbols + `DRAGONECS_DISABLE_POOLS_EVENTS` - выключает реактивное поведение в пулах. + `DRAGONECS_ENABLE_DEBUG_SERVICE` - включает работу EcsDebug в релизном билде. + `DRAGONECS_STABILITY_MODE` - включает опускаемые в релизном билде проверки. + `DRAGONECS_DISABLE_CATH_EXCEPTIONS` - Выключает поведение по умолчанию по обработке исключений. По умолчанию фреймворк будет ловить исключения с выводом информации из исключений через EcsDebug и продолжать работу. + `REFLECTION_DISABLED` - Полностью ограничивает работу фреймворка с Reflection. + `DISABLE_DEBUG` - Для среды где не поддерживается ручное отключение DEBUG, например Unity.
# Расширение фреймворка Дополнительные инструменты полезные для создания расширений. ## Конфиги Конструкторы классов `EcsWorld` и `EcsPipeline` могут принимать контейнеры конфигов реализующие интерфейс `IConfigContainer` или `IConfigContainerWriter`. С помощью этих контейнеров можно передавать данные и зависимости. Встроенная реализация контейнера - `ConfigContainer`, но можно так же использовать свою реализацию.
Пример использования конфигов для мира: ``` c# var configs = new ConfigContainer() .Set(new EcsWorldConfig(entitiesCapacity: 2000, poolsCapacity: 2000) .Set(new SomeDataA(/* ... */)) .Set(new SomeDataB(/* ... */))); EcsDefaultWorld _world = new EcsDefaultWorld(configs); // ... var _someDataA = _world.Configs.Get(); var _someDataB = _world.Configs.Get(); ``` Пример использования конфигов для пайплайна: ``` c# _pipeline = EcsPipeline.New()// аналогично _pipeline = EcsPipeline.New(new ConfigContainer()) .Configs.Set(new SomeDataA(/* ... */)) .Configs.Set(new SomeDataB(/* ... */)) // ... .BuildAndInit(); // ... var _someDataA = _pipeline.Configs.Get(); var _someDataB = _pipeline.Configs.Get(); ``` ## Компоненты Мира С помощью компонентов можно прикреплять дополнительные данные к мирам. В качестве компонентов используются `struct` типы. Доступ к компонентам через `Get` оптимизирован, скорость почти такая же как доступ к полям класса. ``` c# // Получить компонент. ref WorldComponent component = ref _world.Get(); ``` Реализация компонента: ``` c# public struct WorldComponent { // Данные. } ``` Или: ``` c# public struct WorldComponent : IEcsWorldComponent { // Данные. void IEcsWorldComponent.Init(ref WorldComponent component, EcsWorld world) { // Действия при инициализации компонента. Вызывается до первого возвращения из EcsWorld.Get . } void IEcsWorldComponent.OnDestroy(ref WorldComponent component, EcsWorld world) { // Действия когда вызывается EcsWorld.Destroy. // Вызов OnDestroy, обязует пользователя вручную обнулять компонент, если это необходимо. component = default; } } ```

Пример использования

События интерфейса IEcsWorldComponent, могут быть использованы для автоматической инициализации полей компонента, и освобождения ресурсов. ``` c# public struct WorldComponent : IEcsWorldComponent { private SomeClass _object; // Объект который будет утилизироваться. private SomeReusedClass _reusedObject; // Объект который будет переиспользоваться. public SomeClass Object => _object; public SomeReusedClass ReusedObject => _reusedObject; void IEcsWorldComponent.Init(ref WorldComponent component, EcsWorld world) { if (component._reusedObject == null) component._reusedObject = new SomeReusedClass(); component._object = new SomeClass(); // Теперь при получении компонента через EcsWorld.Get, _reusedObject и _object уже будут созданы. } void IEcsWorldComponent.OnDestroy(ref WorldComponent component, EcsWorld world) { // Утилизируем не нужный объект, и освобождаем ссылку на него, чтобы GC мог его собрать. component._object.Dispose(); component._object = null; // Как вариант тут можно сделать сброс значений у переиспользуемого объекта. //component._reusedObject.Reset(); // Так как в этом примере не нужно полное обнуление компонента, то строчка ниже не нужна. // component = default; } } ```

> Компоненты и конфиги можно применять для создания расширений в связке с методами расширений.
# Проекты на DragonECS ## С исходниками:

3D Platformer (Example)

Tiny Aliens (Ludum Dare 56)

## Опубликованные проекты:

Crystal Siege	Order matters
Башенки Смерти	_____________

# FAQ ## Как Выключать/Включать системы? Напрямую - никак.
Обычно потребность выключить/включить систему появляется когда поменялось общее состояние игры, это может так же значить что нужно переключить сразу группу систем, все это в совокупности можно рассматривать как изменения процессов. Есть 2 решения：
+ Если изменения процесса глобальные, то создать новый `EcsPipeline` и в цикле обновления движка запускать соответствующий пайплайн. + Разделить `IEcsRun` на несколько процессов и в цикле обновления движка запускать соответствующий процесс. Для этого создайте новый интерфейс процесса, раннер для запуска этого интерфейса и получайте раннер через `EcsPipeline.GetRunner()`. ## Перечень рекомендаций [DragonECS-Vault](https://github.com/DCFApixels/DragonECS-Vault)
# Обратная связь + Discord (RU-EN) [https://discord.gg/kqmJjExuCf](https://discord.gg/kqmJjExuCf) + QQ (中文) [949562781](http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=IbDcH43vhfArb30luGMP1TMXB3GCHzxm&authKey=s%2FJfqvv46PswFq68irnGhkLrMR6y9tf%2FUn2mogYizSOGiS%2BmB%2B8Ar9I%2Fnr%2Bs4oS%2B&noverify=0&group_code=949562781)