From 13e3b6466eb75dcb7a1e39e5891c3d44acf5efbf Mon Sep 17 00:00:00 2001 From: Mikhail <99481254+DCFApixels@users.noreply.github.com> Date: Tue, 30 May 2023 17:03:13 +0800 Subject: [PATCH] Update README.md --- README.md | 138 ++---------------------------------------------------- 1 file changed, 5 insertions(+), 133 deletions(-) diff --git a/README.md b/README.md index c183dea..123a877 100644 --- a/README.md +++ b/README.md @@ -12,137 +12,9 @@ The [ECS](https://en.wikipedia.org/wiki/Entity_component_system) Framework aims to maximize usability, modularity, extensibility and performance of dynamic entity changes. > **NOTICE:** The project is a work in progress, API may change. -## Оглавление -* [Установка](#Установка) - * [Unity-модуль](#Unity-модуль) - * [В виде иходников](#В-виде-иходников) -* [Основные концепции](#Основные-концепции) - * [Entity](#Entity) - * [Component](#Component) - * [System](#System) -* [Концепции фреймворка](#Концепции-фреймворка) - * [Pipeline](#Pipeline) - * [Процесс](#Процесс) - * [World](#World) - * [Группа](#Группа) - * [Субъект](#Субъект) - * [Запрос](#Запрос) -* [Debug](#Debug) - * [Атрибуты](#Атрибуты) - * [EcsDebugUtility](#EcsDebugUtility) - * [Debug-Сервис](#Debug-Сервис) -* [Расширения](#Расширения) +## Languages +* [Russian](https://github.com/DCFApixels/DragonECS/blob/main/README-RU.md) -# Установка -* ### 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 -``` -* ### В виде иходников -Фреймворк так же может быть добавлен в проект в виде исходников. - -# Основные концепции -## Entity -Сущности - это то к чему крепятся данные. Реализованны в виде идентификаторов, которых есть 2 вида: -* `int` - однократный идентификатор, применяется в пределах одного тика. Не рекомендуется хранить `int` идентификаторы, в место этого используйте `entlong`; -* `entlong` - долговременный идентификатор, содержит в себе полный набор информации для однозначной идентификации; - -## Component -Компоненты - это данные для сущностей. Обязаны реализовывать интерфейс IEcsComponent или другой указываюший вид компонента. -```c# -struct Health : IEcsComponent -{ - public float health; - public int armor; -} -``` -### Встроенные виды компонентов -* `IEcsComponent` - Компоненты с данными. -* `IEcsTagComponent` - Компоненты-теги. Без данных. - -## System -Системы - это основная логика, тут задается поведение сущьностей. Существуют в виде пользовательских классов, реализующих как минимум один из IEcsInitProcess, IEcsDestroyProcess, IEcsRunProcess интерфейсов. -```c# -class UserSystem : IEcsPreInitProcess, IEcsInitProcess, IEcsRunProcess, IEcsDestroyProcess -{ - public void PreInit (EcsSession session) { - // Будет вызван один раз в момент работы EcsSession.Init() и до срабатывания IEcsInitProcess.Init() - } - public void Init (EcsSession session) { - // Будет вызван один раз в момент работы EcsSession.Init() и после срабатывания IEcsPreInitProcess.PreInit() - } - public void Run (EcsSession session) { - // Будет вызван один раз в момент работы EcsSession.Run(). - } - public void Destroy (EcsSession session) { - // Будет вызван один раз в момент работы EcsSession.Destroy() - } - //Для реализации дополнительных процессов используйте Раннеры -} -``` -# Концепции фреймворка -## Pipeline -Класс EcsPipeline является контейнером и двжиком систем, определяя поочередность их вызова, предоставляющий механизм для сообщений между системами и механизм внедрения зависимостей в системы. - -## Process -Процессы - это очереди систем реализующие общий интерфейс, например IEcsRunProcess. Для запуска процессов используются Runner-ы. Система ранеров и процессов может использоваться для создания реактивного поведения или для управления очередью вызова систем. Встроенные процессы вызываются автоматически, для ручного запуска испольщуйте раннеры получаемые из EcsPipeline.GetRunner(). -> Метод GetRunner относительно медленный, поэтому рекомендуется кешировать полученные раннеры. - -### Встроенные процессы: -* `IEcsPreInitProcess`, `IEcsInitProcess`, `IEcsRunProcess`, `IEcsDestroyProcess` - процессы жизненого цикла Pipeline -* `IEcsPreInject`, `IEcsInject` - процессы системы внедрения зависимостей для Pipeline. Через них прокидываются зависимости -* `IEcsPreInitInjectProcess` - Так же процесс системы внедрения зависимостей, но работает в пределах до выполнения IEcsInitProcess, сигнализирует о инициализации предварительных внедрений и окончании. - -### Пользовательские Раннеры и Процессы -Для добавления нового процесса создайте интерфейс наследованный от IEcsSystem и создайте раннер для него. Раннеры это классы реализующие интерфейс запускаемого процесса и наследуемые от EcsRunner. Пример реализации раннера для IEcsRunProcess: - ```c# -public sealed class EcsRunRunner : EcsRunner, IEcsRunProcess -{ - public void Run(EcsSession session) - { - foreach (var item in targets) item.Run(session); - } -} -``` -> Раннеры имеют ряд требований к реализации: -> * Для одного интерфейса может быть только одна реализация раннера; -> * Наследоваться от `EcsRunner` можно только напрямую; -> * Раннер может содержать только один интерфейс(за исключением `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трибутов. -## EcsDebug -EcsDebug Содержит в себе - -# Расширения -* [Автоматическое внедрение зависимостей](https://github.com/DCFApixels/DragonECS-AutoInjections) -* Интеграция с движком Unity (Work in progress) +# Extensions +* [Dependency autoinjections](https://github.com/DCFApixels/DragonECS-AutoInjections) +* Unity integration (Work in progress)