diff --git a/README.md b/README.md index c378567..7bf39a5 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,54 @@ +

+ +

- +Version +

# DragonECS - C# Entity Component System Framework -> **ВАЖНО!** Проект в стадии разработки. API может меняться. README так же не завершен. +> **ВАЖНО!** Проект в стадии разработки. API может меняться. + +## Оглавление +* [Установка](#Установка) + * [Unity-модуль](#Unity-модуль) + * [В виде иходников](#В-виде-иходников) +* [Основные концепции](#Основные-концепции) + * [Entity](#Entity) + * [Component](#Component) + * [System](#System) +* [Концепции фреймворка](#Концепции-фреймворка) + * [Pipeline](#Pipeline) + * [Процесс](#Процесс) + * [World](#World) + * [Группа](#Группа) + * [Субъект](#Субъект) + * [Запрос](#Запрос) +* [Debug](#Debug) + * [Атрибуты](#Атрибуты) + * [EcsDebugUtility](#EcsDebugUtility) + * [Debug-Сервис](#Debug-Сервис) +* [Расширения](#Расширения) + +# Установка +* ### 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 +``` +* ### В виде иходников +Фреймворк так же может быть добавлен в проект в виде исходников. # Основные концепции -## Сущьность -Сущьности - это идентификаторы, к которым крепятся данные. Есть 2 типа идентификатора: +## Entity +Сущности - это то к чему крепятся данные. Реализованны в виде идентификаторов, которых есть 2 вида: * `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется хранить `int` идентификаторы, в место этого используйте `entlong`; * `entlong` - долговременный идентификатор, содержит в себе полный набор информации для однозначной идентификации; -## Компонент -Компоненты - это даные для сущностей. Могут быть тольно struct и обязаны реализовывать интерфейс IEcsComponent или другой указываюший вид компонента. +## Component +Компоненты - это данные для сущностей. Обязаны реализовывать интерфейс IEcsComponent или другой указываюший вид компонента. ```c# struct Health : IEcsComponent { @@ -22,13 +56,11 @@ struct Health : IEcsComponent public int armor; } ``` -### Виды компонентов -* `IEcsComponent` - Компоненты с данными; -* `IEcsTagComponent` - Компоненты-теги. Без данных; -* `IEcsNotNullComponent` - Не нулевые компоненты. Содержатся на всех сущностях, не могут быть добавленыили удалены; -* `IEcsSingleComponent` - Компоненты-одиночки. Имеют только один экземпляр который можнжет быть добавлен или удален с сущности; +### Встроенные виды компонентов +* `IEcsComponent` - Компоненты с данными. +* `IEcsTagComponent` - Компоненты-теги. Без данных. -## Система +## System Системы - это основная логика, тут задается поведение сущьностей. Существуют в виде пользовательских классов, реализующих как минимум один из IEcsInitProcess, IEcsDestroyProcess, IEcsRunProcess интерфейсов. ```c# class UserSystem : IEcsPreInitProcess, IEcsInitProcess, IEcsRunProcess, IEcsDestroyProcess @@ -48,15 +80,15 @@ class UserSystem : IEcsPreInitProcess, IEcsInitProcess, IEcsRunProcess, IEcsDest //Для реализации дополнительных процессов используйте Раннеры } ``` - +# Концепции фреймворка ## Pipeline -Является двжиком систем, определяя поочередность их вызова, предоставляющий механизм для сообщений между системами и механизм внедрения зависимостей в системы. +Класс EcsPipeline является контейнером и двжиком систем, определяя поочередность их вызова, предоставляющий механизм для сообщений между системами и механизм внедрения зависимостей в системы. -## Процесс/Раннер -Процессы - это очереди систем реализующие общий интерфейс. Раннеры запускюат выполнение процессов. Система раннеров и процессов может использоваться для создания реактивного поведения или для управления очередью вызова систем. Встроенные процессы вызываются автоматически, для ручного запуска испольщуйте раннеры получаемые из EcsPipeline.GetRunner(). +## Process +Процессы - это очереди систем реализующие общий интерфейс, например IEcsRunProcess. Для запуска процессов используются Runner-ы. Система ранеров и процессов может использоваться для создания реактивного поведения или для управления очередью вызова систем. Встроенные процессы вызываются автоматически, для ручного запуска испольщуйте раннеры получаемые из EcsPipeline.GetRunner(). > Метод GetRunner относительно медленный, поэтому рекомендуется кешировать полученные раннеры. -Встроенные процессы: +### Встроенные процессы: * `IEcsPreInitProcess`, `IEcsInitProcess`, `IEcsRunProcess`, `IEcsDestroyProcess` - процессы жизненого цикла Pipeline * `IEcsPreInject`, `IEcsInject` - процессы системы внедрения зависимостей для Pipeline. Через них прокидываются зависимости * `IEcsPreInitInjectProcess` - Так же процесс системы внедрения зависимостей, но работает в пределах до выполнения IEcsInitProcess, сигнализирует о инициализации предварительных внедрений и окончании. @@ -78,3 +110,37 @@ public sealed class EcsRunRunner : EcsRunner, IEcsRunProcess > * Раннер может содержать только один интерфейс(за исключением `IEcsSystem`); > * Наследуемый класс `EcsRunner,` в качестве `TInterface` должен принимать реализованный интерфейс; > * Раннер не может быть размещен внутри другого класса. + +## World +Является контейнером для сущностей и компонентов. + +## Группа +Группы это структуры данных для хранения списка сущностей и с быстрыми операциями добавления/удаления/проверки наличия и т.д. Реализованы классом EcsGroup и структурой EcsReadonlyGroup. + +## Пул +Является контейнером для компонентов, предоставляет методы для добавления/чтения/редактирования/удаления компонентов на сущности. Есть несколько видов пулов, для разных целей +* `EcsPool` - универсальный пул, хранит struct-компоненты реализующие интерфейс IEcsComponent; +* `EcsTagPool` - подходит для хранения пустых компонентов-тегов, в сравнении с EcsPool имеет лучше оптимизацию памяти и дейсвий с пулом, хранит в себе struct-компоненты реализующие IEcsTagComponent; + +Так же имеется возможность реализации пользовательского пула +## Субъект +Это классы наследуемые от EcsSubject, которые используются как посредник для взаимодейсвия с сушностями. + +## Запросы +Используйте метод-запрос `EcsWorld.Where(out TSubject subject)` для получения необходимого системе набора сущностей. Запросы работают в связке с субъектами, субъекты определяют ограничения запросов, результатом запроса становится группа сущностей удовлетворяющия условиям субъекта. По умолчанию запрос делает выборку из всех сущностей в мире, но так же можно сделать выборку из определенной группы сущностей, для этого используйте `EcsWorld.WhereFor(EcsReadonlyGroup sourceGroup, out TSubject subject)` + +# Debug +Фреймворк предоставляет дополнительные интрументы для отладки и логирования. +## Атрибуты +В чистом виде атрибуты не имеют применения, но будут использоваться в интеграциях с движками для задания отображения в отладочных интурментах и редакторах. +* `DebugNameAttribute` - Задает пользовательское название типа, по умолчанию используется имя типа. +* `DebugColorAttribute` - Задает цвет типа в системе rgb, где каждый канал принимает занчение от 0 до 255, по умолчанию белый. Задать цвет можно как вручную, так и использовать заранее заготовленные цвета в enum DebugColor. +* `DebugDescriptionAttribute` - Добавляет описание типу. +* `DebugHideAttribute` - Скрывает тип. +## EcsDebugUtility +Статические класс EcsDebugUtility имеет набор методов для упрощения получения данных из Debug-Aтрибутов. +## Debug-Сервис + +# Расширения +* [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections) +* Интеграция с движком Unity (Work in progress)