Этот пакет делает работу с DragonECS в Unity удобнее и нагляднее: встроенная визуальная отладка и профайлинг, редакторские шаблоны и инструменты для привязки сущностей к `GameObject`.
> Readme еще не завершен, если есть не ясные моменты, вопросы можно задать тут [Обратная связь](https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md#%D0%BE%D0%B1%D1%80%D0%B0%D1%82%D0%BD%D0%B0%D1%8F-%D1%81%D0%B2%D1%8F%D0%B7%D1%8C)
> Встроенные реализации шаблонов `UnityComponent<T>` были перенесены [СЮДА](https://gist.github.com/DCFApixels/c250f2561f09e09ab3e6a4bd4f3013cb#file-unitycomponenttemplates-cs) Так как некоторые модули Unity отключаемы, и например отключение модуля физики приведет к тому что код реализации `UnityComponent<Rigidbody>` или `UnityComponent<Collider>` не будет компилироваться.
Поддерживается установка в виде Unity-модуля при помощи добавления git-URL [в PackageManager](https://docs.unity3d.com/2023.2/Documentation/Manual/upm-ui-giturl.html):
`UnityDebugService` - реализация [Debug-сервиса для `EcsDebug`](https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md#ecsdebug). В редакторе он инициализируется автоматически и обеспечивает интеграцию: например, вызовы `EcsDebug.Print` направляются в консоль Unity, а`EcsProfilerMarker` подключается к встроенному профайлеру и т.д.
Реализовано в виде объектов-мониторов, в которых отображается состояние разных частей фреймворка. Найти эти мониторы можно в `Play Mode` в разделе `DontDestroyOnLoad`.
Отображает в виде матрицы процессы и системы. Системы отображаются в порядке их выполнения. Точка в пересечении системы и процесса означает что эта система является частью этого процесса.
Расположен вместе с`WorldMonitor`, показывает список всех Where запросов которые выполняли системы. Вверху есть поле для поиска запросов по именам компонентам. Поисковую строку можно разделять символом `/` для одновременного поиска нескольких компонентов. Рядом с каждым Where запросом есть кнопка `Snapshot`, по нажатию откроется окно со списоком всех сущностей которые на данный момент удовлетворяют маске запроса.
Показывает состояние сущности мира, позволяет добавлять/изменять/удалять компоненты по время Play Mode. На каждую сущность в мире создается отдельный монитор. Все мониторы сущностей помещаются в монитор мира.
Чтобы компонент попал в меню `Add Component` требуется шаблон. Шаблоны компонента это типы реализующие `IComponentTemplate` или компоненты реализующие `ITemplateNode` вместе с`IEcsComponentMember`.
Такой способ может быть удобен тем что не требует создания отдельного класса шаблона, компонент сам выступает как шаблон, и он так же прост в реализации. Минус данного подхода, что проще случайно переименовать компонент и получить Missing Reference в местах с атрибутом `[SerializeReference]`.
```c#
public struct Health : IEcsComponent, ITemplateNode
{
public float Points;
public void Apply(short worldID, int entityID)
{
EcsPool<Health>.Apply(worldID, entityID) = this;
}
}
```
#### Реализация кастомного шаблона
Если не подходят встроенные `ComponentTemplate<T>` или `TagComponentTemplate<T>`, можно создать свой шаблон реализующий `IComponentTemplate`. Например это может пригодиться для кастомного пула. В большинстве случаев достаточно использовать встроенные шаблоны.
Связываются сущности и GameObject-ы с помощью коннектов. Коннекты со стороны GameObject - `EcsEntityConnect`, со стороны сущности - `GameObjectConnect`. `EcsEntityConnect` - управляющий коннект, `GameObjectConnect` - создается/удаляется автоматически.
`AutoEntityCreator` автоматический создает сущность и связывает с GameObject. В инспекторе ему нужно указать `EcsEntityConnect`с которым связывать сущность и [Провайдер мира](#world-provider) в котором создать сущность.
> На панели внизу есть вспомогательные кнопки: 1) Автоматическое заполнение ссылки на коннект. 2) Каскадный вызов автозаполнения для всех дочерних экземпляров в иерархии.
`EcsWorldProvider<TWorld>` - это `ScriptableObject` обертка над `TWorld`, предназначенная для пробрасывания экземпляра мира и настройки через инспектор Unity. Для простых случаев достаточно будет использовать синглтон версию провайдера `EcsDefaultWorldSingletonProvider`.
Пайплайн как и сущности можно собирать из шаблонов. Шаблоны пайплайна это модули, реализующие интерфейс `IEcsModule`。
По умолчанию расширение содержит 2 вида шаблонов: `ScriptablePipelineTemplate`, `MonoPipelineTemplate`.
## ScriptablePipelineTemplate
Хранится как отдельный ассет. Наследуется от `ScriptableObject`. Действия чтобы создать `ScriptableEntityTemplate` ассет: `Asset > Create > DragonECS > ScriptablePipelineTemplate`.
Упрощённая реализация Ecs Root для Unity; собирает пайплайн из шаблонов. Наследуется от `MonoBehaviour`. Чтобы добавить на GameObject: `Add Component > DragonECS > EcsRootUnity`.
Применяется к полю с`[SerializeReference]`. Добавляет кнопку выбора типа из списка. Можно ограничить набор доступных типов, передав список в конструктор.
+ **[ReferenceDropDownWithout]** -
Используется вместе с`[ReferenceDropDown]`, чтобы исключить указанные типы (и их наследников) из списка выбора.
+ **[DragonMetaBlock]** -
Отображает значение в инспекторе так же, как компоненты в шаблонах сущности. Учитывает meta-атрибуты (`MetaGroup`, `MetaColor`, `MetaDescription`, `MetaID` и др.).
## Поведение Meta-атрибутов
+ Иерархическая группировка элементов в меню `Add Component` или `[ReferenceDropDown]` задаётся через `[MetaGroup]`.
+ Цвет компонента в инспекторе по умолчанию определяется именем типа. Режим окраски можно изменить в окне настроек. Явный цвет задаётся через `[MetaColor]`.
+ При совпадении имени типа и файла (или при наличии `[MetaID]`) рядом с кнопкой удаления появляется иконка файла: один клик — выделение скрипта в проекте, двойной клик — открытие.
+ Если указан `[MetaDescription]`, рядом отображается иконка подсказки с текстом описания.
+ При восстановлении **Missing Reference**с помощью [**Reference Repairer**](#Reference-Repairer), инструмент ищет соответствие старого и нового имени типа по атрибуту `[MetaID(id)]`.
## Примеры:
Атрибут `DragonMetaBlock`:
```c#
// Отображение поля настраиваемое мета-атрибутами.
// Аналогично компонентам в MonoEntityTemplate или ScriptableEntityTemplate.
[DragonMetaBlock]
public SomeComponent Component;
// Можно применять к любому полю любого типа.
[DragonMetaBlock]
public Foo Foo;
```
`ReferenceDropDown` и `ReferenceDropDownWithout`:
```c#
// Добавляет кнопку выбора реализации ITemplateNode из выпадающего списка.
[SerializeReference]
[ReferenceDropDown]
public ITemplateNode Template;
```
```c#
// Так же можно применять к любому полю любого типа.
// В списке будут только тип Foo и его наследники, исключая FooExc и его наследников.
[SerializeReference]
[ReferenceDropDown(typeof(Foo))]
[ReferenceDropDownWithout(typeof(FooExc))]
public object Template;
```
Комбинирование и другие варианты использования:
```c#
// Атрибуты можно комбинировать.
[DragonMetaBlock]
[ReferenceDropDown]
public ITemplateNode Template;
// Обертка над ITemplateNode, аналогично примеру выше.
public ComponentTemplateProperty Template;
// Атрибуты корректно работают с массивами и листами.
[DragonMetaBlock]
[ReferenceDropDown]
public ITemplateNode[] Template;
```
</br>
# Поддержка Jobs
DragonECS по умолчанию совместим с Job системой Unity. Пример:
```c#
EcsWorld _world;
class Aspect : EcsAspect
{
// Пул для unmanaged компонентов.
public EcsValuePool<Cmp> Cmps = Inc;
}
public void Run()
{
var job = new Job()
{
// Идентично Where, но возвращает unmanaged список сущностей.
В интеграции также есть окно документации проекта на основе мета-атрибутов. Открыть документацию: `Tools > DragonECS > Documentation`. Документация формируется при первом открытии окна и при нажатии кнопки `Update`.
В окне настроек доступно несколько опций, включая режимы отображения компонентов в инспекторе. Внизу находятся переключатели для define-переменных, используемых в фреймворке. Открыть окно настроек: `Tools > DragonECS > Settings`.
Инструмент для восстановления Missing Reference. Некоторые части интеграции активно задействует `[SerializeReference]`, у которого есть известная проблема с потерей типов при переименовании. `Reference Repairer` упрощает процесс восстановления. Он может собирать все ассеты с потерянными типами, после этого предоставляет окно для указания новых имён потерянных типов и выполнит их восстановление в собранных ассетах. Открыть окно инструмента: `Tools > DragonECS > Reference Repairer`.
## Не могу повесить `EcsEntityConnect` или другие компоненты
Иногда это происходит после обновления пакета. Решения: выполните `Assets -> Reimport All` или перезапустите Unity после удаления папки `Library` в корне проекта.
