AlicizaX/DragonECS-Unity
1
0
Fork 0
mirror of https://github.com/DCFApixels/DragonECS-Unity.git synced 2025-09-17 17:34:34 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity
1a138348b5
DragonECS-Unity/README-RU.md
Mikhail 69f633da06
Update README-RU.md
2024-05-17 11:37:09 +08:00

15 KiB
Raw Blame History

Version GitHub Discord

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

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

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

Warning

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

Оглавление


Установка

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

Окружение

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

  • Зависимость: 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 { /*...*/ }
class SomeComponentTemplate : ComponentTemplate<SomeComponent> { }
  • Упрощенная реализация для компонентов-тегов:
[Serializable]
struct SomeTagComponent : IEcsTagComponent { /*...*/ }
class SomeTagComponentTemplate : TagComponentTemplate<SomeComponent> { }
* Полная реализация: 
[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<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) { /*...*/ }
}

В раскрывающемся при нажатии Add Component меню выбора компонента поддердивается иерархическое группирование. Производится группирование на основе мета-атрибута [MetaGroup].

Компоненты в инспектрре по умолчанию отображаются окрашенными в случайный цвет сгенерированный на основе имени компонента, выбрать другой режим окраски можно в настройках фреймворка. Задать конкретный цвет можно при помощи мета-атрибута [MetaColor].

Если у компонента есть мета-атрибут [MetaDescription], то рядом с крестиком удаления компонента будет иконка подсказки, при наведении курсора отобразится в виде подсказки информация из [MetaDescription].

Связь с 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.

На панели внизу есть вспомогательные кнопки: 1) Автоматическое заполнение ссылки на коннект. 2) Каскадный вызов автозаполнения для всех дочерних экземпляров в иерархии.


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