DragonECS-Unity/README-RU.md

Интеграция с Unity для DragonECS

Languages:	Русский	English(WIP)

Расширение добавит набор инструментов для дебага и связи с движком Unity.

Warning

Проект в стадии разработки. API может меняться.
Readme еще не завершен

Оглавление

• Установка
• Debug
  • Debug Модуль
  • Debug Сервис
  • Визуальная отладка
• Шаблоны
• Связь с GameObject
• World Provider
• FixedUpdate LateUpdate

Установка

Семантика версионирования - Открыть

Окружение

Обязательные требования:

• Зависимость: DragonECS
• Минимальная версия C# 7.3;
• Минимальная версия Unity 2021.2.0;

Протестированно:

• Unity: Минимальная версия 2021.2.0;

Установка для Unity

• Unity-модуль

Поддерживается установка в виде Unity-модуля в при помощи добавления git-URL в PackageManager или ручного добавления в Packages/manifest.json:

https://github.com/DCFApixels/DragonECS-Unity.git

• В виде иходников

Фреймворк так же может быть добавлен в проект в виде исходников.

Debug

Debug Модуль

Подключение модуля отладки в Unity.

EcsDefaultWorld _world = new EcsDefaultWorld();
EcsEventWorld _eventWorld = new EcsDefaultWorld();

_pipeline = EcsPipeline.New()
    //...
    // Подключение и инициализация отладки для миров _world и _eventWorld
    .AddUnityDebug(_world, _eventWorld)
    //...
    .BuildAndInit();

Debug Сервис

UnityDebugService- реализация Debug-сервиса для EcsDebug. В редакторе по умолчанию автоматически инициализируется и связывает EcsDebug.Print с консолью юнити, EcsProfilerMarker 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.

ITemplateNode someSamplate = /*...*/;
//...
foreach (var e in _world.Where(out Aspect a))
{
    // Применение шаблона сущности.
    someSamplate.Apply(e, _world.id);
}

// Применение шаблона сразу при создании сущности.
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.

• Упрощенная реализация:

// Обязательно добавить [Serializable] к компоненту и к шаблону
[Serializable]
struct SomeComponent : IEcsComponent { /*...*/ }
[Serializable]
class SomeComponentTemplate : ComponentTemplate<SomeComponent> { }

• Упрощенная реализация для компонентов-тегов:

[Serializable]
struct SomeTagComponent : IEcsTagComponent { /*...*/ }
[Serializable]
class SomeTagComponentTemplate : TagComponentTemplate<SomeComponent> { }

• Полная реализация:

[Serializable] 
struct SomeComponent : IEcsComponent { /*...*/ }
[Serializable]
class SomeComponentTemplate : IComponentTemplate
{
    [SerializeField]
    protected SomeComponent component;
    public Type Type { get { return typeof(SomeComponent); } }
    public void Apply(int worldID, int entityID)
    {
        EcsWorld.GetPoolInstance<EcsPool<SomeComponent>>(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) { /*...*/ }
}

Чтобы компонент можно было добавить в шаблон, нужно реализовать шаблон компонента.

Связь с GameObject

Связываются сущности и GameObject-ы с помощью коннектов. Коннекты со стороны GameObject - EcsEntityConnect, со стороны сущности - GameObjectConnect. EcsEntityConnect - ключевой коннект, GameObjectConnect - создается/удаляется автоматически.

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 с которым связывать сущность и Провайдер мира в котормо создать сущность.

Повесить компонент: Add Component > DragonECS > AutoEntityCreator.

World Provider

EcsWorldProvider - это ScriptableObject обертка над EcsWorld, предназначенная для пробрасывания экземпляра мира и настройки через инспектор Unity. Для простых случаев достаточно будет использовать синглтон версию провайдера EcsDefaultWorldSingletonProvider.

Создать ассет провайдера: Asset > Create > DragonECS > WorldProviders > Выбрать тип мира.

FixedUpdate LateUpdate

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();
    }
    // ...
}