Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dcfapixels/dragonecs
C# Entity Component System framework
https://github.com/dcfapixels/dragonecs
csharp dragon-ecs dragonecs ecs ecs-framework entity-component-system game-development gamedev no-dependencies unity
Last synced: 20 days ago
JSON representation
C# Entity Component System framework
- Host: GitHub
- URL: https://github.com/dcfapixels/dragonecs
- Owner: DCFApixels
- License: mit
- Created: 2023-02-01T09:07:08.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-10T15:37:32.000Z (9 months ago)
- Last Synced: 2024-04-10T23:58:49.067Z (9 months ago)
- Topics: csharp, dragon-ecs, dragonecs, ecs, ecs-framework, entity-component-system, game-development, gamedev, no-dependencies, unity
- Language: C#
- Homepage:
- Size: 1.08 MB
- Stars: 62
- Watchers: 2
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README-RU.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:** Минимальная версия 2020.1.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) или ручного добавления в `Packages/manifest.json`:
```
https://github.com/DCFApixels/DragonECS.git
```
* ### В виде исходников
Фреймворк так же может быть добавлен в проект в виде исходников.
# Основные концепции
## Entity
**Сущности** - это то к чему крепятся данные. Реализованы в виде идентификаторов, которых есть 2 вида:
* `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется хранить `int` идентификаторы, в место этого используйте `entlong`;
* `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 () { }
}
```
> Для реализации дополнительных процессов перейдите к разделу [Процессы](#Процессы).
# Концепции фреймворка
## Пайплайн
Контейнер и движок систем. Отвечает за настройку очереди вызова систем, предоставляет механизм для сообщений между системами и механизм внедрения зависимостей. Реализован в виде класса `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#
using DCFApixels.DragonECS;
// ...
class Aspect : EcsAspect
{
// Кешируется пул и Pose добавляется во включающее ограничение.
public EcsPool poses = Inc;
// Кешируется пул и Velocity добавляется во включающее ограничение.
public EcsPool velocities = Inc;
// Кешируется пул и FreezedTag добавляется в исключающее ограничение.
public EcsTagPool freezedTags = Exc;
// При запросах будет проверяться наличие компонентов
// из включающего ограничения маски и отсутствие из исключающего.
// Так же есть Opt - только кеширует пул, не влияя на маску.
}
```
Явный синтаксис (результат идентичен примеру выше):
``` c#
using DCFApixels.DragonECS;
// ...
class Aspect : EcsAspect
{
public EcsPool poses;
public EcsPool velocities;
protected override void Init(Builder b)
{
poses = b.Include();
velocities = b.Include();
b.Exclude();
}
}
```
Комбинирование аспектов
В аспекты можно добавлять другие аспекты, тем самым комбинируя их. Ограничения так же будут скомбинированы.
``` c#
using DCFApixels.DragonECS;
// ...
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(EcsMask mask)` - Обычная фильтрация по маске;
+ `EcsWorld.Where(out TAspect aspect)` - Сочетает в себе фильтрацию по маске из аспекта и получение аспекта;
Запрос `Where` применим как к `EcsWorld` так и коллекциям фреймворка (в этом плане 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 Inject(EcsDefaultWorld world) => _world = world;
public void Run()
{
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);
}
}
}
}
}
```
> Имеется [Расширение](#расширения) упрощающее синтаксис запросов и обращения к компонентам - [Упрощенный синтаксис](https://github.com/DCFApixels/DragonECS-AutoInjections).
## Коллекции
### EcsSpan
Коллекция сущностей, доступная только для чтения и выделяемая только в стеке. Состоит из ссылки на массив, длинны и идентификатора мира. Аналог `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
+ `DISABLE_POOLS_EVENTS` - выключает реактивное поведение в пулах.
+ `ENABLE_DRAGONECS_DEBUGGER` - включает работу EcsDebug в релизном билде.
+ `ENABLE_DRAGONECS_ASSERT_CHECKS` - включает опускаемые в релизном билде проверки.
+ `REFLECTION_DISABLED` - Полностью ограничивает работу фреймворка с Reflection.
+ `DISABLE_DEBUG` - Для среды где не поддерживается ручное отключение DEBUG, например Unity.
+ `ENABLE_DUMMY_SPAN` - На случай если в среде не поддерживаются Span типы, включает его замену.
+ `DISABLE_CATH_EXCEPTIONS` - Выключает поведение по умолчанию по обработке исключений. По умолчанию фреймворк будет ловить исключения с выводом информации из исключений через EcsDebug и продолжать работу.
# Расширение фреймворка
Дополнительные инструменты полезные для создания расширений.
## Конфиги
Конструкторы классов `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)
## Опубликованные проекты:
Башенки Смерти
ㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤㅤ
# Расширения
* Пакеты:
* [Интеграция с движком Unity](https://github.com/DCFApixels/DragonECS-Unity)
* [Автоматическое внедрение зависимостей](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)
* [Однокадровые компоненты](https://gist.github.com/DCFApixels/46d512dbcf96c115b94c3af502461f60)
* [Шаблоны кода IDE](https://gist.github.com/ctzcs/0ba948b0e53aa41fe1c87796a401660b) и [для Unity](https://gist.github.com/ctzcs/d4c7730cf6cd984fe6f9e0e3f108a0f1)
> *Твое расширение? Если разрабатываешь расширение для DragonECS, пиши [сюда](#обратная-связь).
# FAQ
## 'ReadOnlySpan<>' could not be found
В версии Unity 2020.1.х в консоли может выпадать ошибка:
```
The type or namespace name 'ReadOnlySpan<>' could not be found (are you missing a using directive or an assembly reference?)
```
Чтобы починить добавьте директиву `ENABLE_DUMMY_SPAN` в `Project Settings/Player/Other Settings/Scripting Define Symbols`.
## Как Выключать/Включать системы?
Напрямую - никак.
Обычно потребность выключить/включить систему появляется когда поменялось общее состояние игры, это может так же значить что нужно переключить сразу группу систем, все это в совокупности можно рассматривать как изменения процессов. Есть 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)
