# Интеграция с Unity для [DragonECS](https://github.com/DCFApixels/DragonECS)
| Languages: | [Русский](https://github.com/DCFApixels/DragonECS-Unity/blob/main/README-RU.md) | [English(WIP)](https://github.com/DCFApixels/DragonECS-Unity) |
| :--- | :--- | :--- |
Расширение добавит набор инструментов для дебага и связи с движком Unity.
> [!WARNING]
> Проект в стадии разработки. API может меняться.
> Readme еще не завершен
# Оглавление
- [Установка](#установка)
- [Debug](#debug)
- [Debug Модуль](#debug-модуль)
- [Debug Сервис](#debug-сервис)
- [Визуальная отладка](#визуальная-отладка)
- [Шаблоны](#шаблоны)
- [Связь с GameObject](#связь-с-gameobject)
- [World Provider](#world-provider)
- [FixedUpdate LateUpdate ](#fixedupdate-lateupdate)
# Установка
Семантика версионирования - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md)
## Окружение
Обязательные требования:
+ Зависимость: [DragonECS](https://github.com/DCFApixels/DragonECS)
+ Минимальная версия C# 7.3;
+ Минимальная версия Unity 2021.2.0;
Протестированно:
+ **Unity:** Минимальная версия 2021.2.0;
## Установка для 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-Unity.git
```
* ### В виде иходников
Фреймворк так же может быть добавлен в проект в виде исходников.
# Debug
## Debug Модуль
Подключение модуля отладки в Unity.
```c#
EcsDefaultWorld _world = new EcsDefaultWorld();
EcsEventWorld _eventWorld = new EcsDefaultWorld();
_pipeline = EcsPipeline.New()
//...
// Подключение и инициализация отладки для миров _world и _eventWorld
.AddUnityDebug(_world, _eventWorld)
//...
.BuildAndInit();
```
## Debug Сервис
`UnityDebugService`- реализация [Debug-сервиса для `EcsDebug`](https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md#ecsdebug). В редакторе по умолчанию автоматически инициализируется и связывает `EcsDebug.Print` с консолью юнити, `EcsProfilerMarker` c профайлером и т.д.
```c#
//Ручная активация.
UnityDebugService.Activate();
//Выведет сообщение в консоле Unity.
EcsDebug.Print();
var someMarker = new EcsProfilerMarker("SomeMarker");
someMarker.Begin();
//время выполнения этого участка будет отражено в профайлере юнити.
someMarker.End();
//Остановка игрового режима.
EcsDebug.Break();
```
## Визуальная отладка
Выполнена в виде специальных объектов-мониторов в которых отображается состояние разных аспектов фреймворка. Найти эти мониторы можно в Play Mode в разделе `DontDestroyOnLoad`.
-----
* ### `PipelineMonitor`
Показывает состояние `EcsPipeline`. Системы отображаются в порядке их выполнения.
-----
* ### `PipelineProcessMonitor`
Отображает в виде матрицы процессы и сситемы. Системы отображабтся в порядке их выполнения. Точка в пересечении системы и процесса означает что эта система является частью этого процесса.
-----
* ### `WorldMonitor`
Показывает состояние `EcsWorld`. на каждый казанный мир создается отдельный монитор.
-----
* ### `EntityMonitor`
Показывает состояние сущности мира. На кажду сущность в мире создается отдельынй монитор. Все мониторы сущностей помещаются в монитор мира.
-----
# Шаблоны
Шаблоны - это настраиваемые наборы компонентов которые можно применить к сущностям. Шаблоны должны реализовавыть интерфейс `ITemplateNode`.
```c#
ITemplateNode someSamplate = /*...*/;
//...
foreach (var e in _world.Where(out Aspect a))
{
// Применение шаблона сущности.
someSamplate.Apply(e, _world.id);
}
```
```c#
// Применение шаблона сразу при создании сущности.
int e = _world.NewEntity(someSamplate);
```
По умолчанию расширение содержит 2 вида шаблонов: `ScriptableEntityTemplate`, `MonoEntityTemplate`.
## ScriptableEntityTemplate
Хранится как отдельынй ассет. Наследуется от `ScriptableObject`.
Дейсвия чтобы создать `ScriptableEntityTemplate` ассет:
Создать ассет: Asset > Create > DragonECS > ScriptableEntityTemplate.
Чтобы добавить компонент в меню `Add Component` Нужен [Шаблон компонента](#шаблон-компонента). Пример:
-----
## MonoEntityTemplate
Крепится к GameObject. Наследуется от `MonoBehaviour`.
Повесить компонент: Add Component > DragonECS > MonoEntityTemplate.
Чтобы добавить компонент в меню `Add Component` Нужен [Шаблон компонента](#шаблон-компонента). Пример:
-----
## Шаблон компонента
Чтобы компонент попал в меню `Add Component` нужно реализовать шаблон компонента. Шаблоны компонента это типы реализующие `IComponentTemplate`.
* Упрощенная реализация:
```c#
// Обязательно добавить [Serializable] к ттипу компонента
[Serializable]
struct SomeComponent : IEcsComponent { /*...*/ }
class SomeComponentTemplate : ComponentTemplate { }
```
* Упрощенная реализация для компонентов-тегов:
```c#
[Serializable]
struct SomeTagComponent : IEcsTagComponent { /*...*/ }
class SomeTagComponentTemplate : TagComponentTemplate { }
```
* Полная реализация:
```c#
[Serializable]
struct SomeComponent : IEcsComponent { /*...*/ }
class SomeComponentTemplate : IComponentTemplate
{
[SerializeField]
protected SomeComponent component;
public Type Type { get { return typeof(SomeComponent); } }
public void Apply(int worldID, int entityID)
{
EcsWorld.GetPoolInstance>(worldID).TryAddOrGet(entityID) = component;
}
public object GetRaw() { return component; }
public void SetRaw(object raw) { component = (SomeComponent)raw; }
public void OnGizmos(Transform transform, IComponentTemplate.GizmosMode mode) { /*...*/ }
public void OnValidate(UnityEngine.Object obj) { /*...*/ }
}
```
В раскрывающемся при нажатии `Add Component` меню выбора компонента поддердивается иерархическое группирование. Производится группирование на основе мета-атрибута `[MetaGroup]`.
Компоненты в инспектрре по умолчанию отображаются окрашенными в случайный цвет сгенерированный на основе имени компонента, выбрать другой режим окраски можно в настройках фреймворка. Задать конкретный цвет можно при помощи мета-атрибута `[MetaColor]`.
Если у компонента есть мета-атрибут `[MetaDescription]`, то рядом с крестиком удаления компонента будет иконка подсказки, при наведении курсора отобразится в виде подсказки информация из `[MetaDescription]`.
# Связь с GameObject
Связываются сущности и GameObject-ы с помощью коннектов. Коннекты со стороны GameObject - `EcsEntityConnect`, со стороны сущности - `GameObjectConnect`. `EcsEntityConnect` - управляющий коннект, `GameObjectConnect` - создается/удаляется автоматически.
```c#
EcsEntityConnect connect = /*...*/;
entlong entity = _world.NewEntityLong();
// Связывание сущности с GameObject.
// Автоматически добавляется GameObjectConnect в сущность.
// Автоматическки применяются шаблоны.
connect.ConnectWith(entity);
// Или создать без применения шаблнов.
connect.ConnectWith(entity, false);
// Отвязать.
// Автоматически удалится GameObjectConnect.
connect.Disconnect();
```
Повесить компонент: Add Component > DragonECS > EcsEntityConnect.
> Просмотреть все компоненты связанной сущности можно развернув `RUNTIME COMPONENTS`.
> На панели внизу есть вспомогательные кнопки: 1) Отвязать сущность. 2) Удалить сущность. 3) Автоматическое заполнение массива шаблонов. 4) Каскадный вызов автозаполнения для всех дочерних коннектов в иерархии.
---
`AutoEntityCreator` автоматический создает сущность и связывает с GameObject. В инспекторе ему нужно указать `EcsEntityConnect` с которым связывать сущность и [Провайдер мира](#world-provider) в котормо создать сущность.
Повесить компонент: Add Component > DragonECS > AutoEntityCreator.
> На панели внизу есть вспомогательные кнопки: 1) Автоматическое заполнение ссылки на коннект. 2) Каскадный вызов автозаполнения для всех дочерних экземпляров в иерархии.
# World Provider
`EcsWorldProvider` - это `ScriptableObject` обертка над `EcsWorld`, предназначенная для пробрасывания экземпляра мира и настройки через инспектор Unity. Для простых случаев достаточно будет использовать синглтон версию провайдера `EcsDefaultWorldSingletonProvider`.
Создать ассет провайдера: Asset > Create > DragonECS > WorldProviders > Выбрать тип мира.
# FixedUpdate LateUpdate
```c#
using DCFApixels.DragonECS;
using UnityEngine;
public class EcsRoot : MonoBehaviour
{
private EcsPipeline _pipeline;
//...
private void Update()
{
// Стандартный Run из фреймворка.
_pipeline.Run();
}
private void FixedUpdate()
{
// Специальный Run для трансляции FixedUpdate.
_pipeline.FixedRun();
}
private void LateUpdate()
{
// Специальный Run для трансляции LateUpdate.
_pipeline.LateRun();
}
// ...
}
```