Version License Discord QQ

# Графы сущностей для [DragonECS](https://github.com/DCFApixels/DragonECS)
Readme Languages:

Русский

English(WIP)

Реализация отношений сущностей в виде графа. Связывающие ребра графа представлены в виде сущностей, что позволяет создавать отношения вида многие ко многим, а с помощью компонентной композиции можно настраивать вид этих отношений. > [!WARNING] > Проект в стадии разработки. API может меняться. # Оглавление - [Установка](#установка) - [Инициализация](#инициализация)
# Установка Семантика версионирования - [Открыть](https://gist.github.com/DCFApixels/e53281d4628b19fe5278f3e77a7da9e8#file-dcfapixels_versioning_ru-md) ## Окружение Обязательные требования: + Зависимость: [DragonECS](https://github.com/DCFApixels/DragonECS) + Минимальная версия C# 7.3; Опционально: + Игровые движки с C#: Unity, Godot, MonoGame и т.д. Протестировано: + **Unity:** Минимальная версия 2020.1.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-Graphs.git ``` * ### В виде исходников Пакет так же может быть добавлен в проект в виде исходников.
# Граф Ключевой класс в котором хранится информация об отношениях. Графу требуется 2 мира: обычный мир и мир для сущностей-связей. Пример создания `EntityGraph`: ```c# // Обычный мир. _world = new EcsDefaultWorld(); // EcsGraphWorld специальный тип мира для сущностей-связей, // но может использоваться любой другой тип мира. _graphWorld = new EcsGraphWorld(); // Создание EntityGraph связывающий эти два мира. EntityGraph graph = _world.CreateGraph(_graphWorld); _pipeline = EcsPipeline.New() // ... // Далее миры и граф можно внедрить в системы. .Inject(_world, _graphWorld, graph) // ... .Build() ``` Для обычных сущностей и для сущностей-связей может использовать один общий мир: ```c# _world = new EcsDefaultWorld(); // Создание EntityGraph завязанный на одном мире. EntityGraph graph = _world.CreateGraph(); ``` # Сущность-связь Как и обычная сущность, но регистрируется и создается в `EntityGraph`. Предназначена для данных об отношении двух сущностей. > Отношения имеют направление, поэтому чтобы разделять сущности, далее будет использованы понятия: начальная сущность(`Start Entity`) от нее исходит сущность-связъ(`Relation Entity`) к конечной сущности(`End Entity`). Начальная и конечная сущность это сущности-узлы(`Node Entity`). > > (Start Entity) ── (Relation Entity) ─》(End Entity) Пример работы с связями: ```c# // Получаем или создаем новую сущность-связь от узлов `startE` к `endE`. // Сущность создается в мире _graph.GraphWorld и регистрируется в графе. var relE = _graph.GetOrNewRelation(startE, endE); // Кроме создания и удаления, в остальном сущности-связи - это обычные сущности. ref var someCmp = ref _somePool.Add(relE); // Вернет true если была создана через EntityGraph.GetOrNewRelation(startE, endE) // и false если через EcsWorld.NewEntity(). bool isRelation = _graph.IsRelation(relE); // Получить начальную и конечную сущность. (startE, endE) = _graph.GetRelationStartEnd(relE); // Взять сущность-связь для отношения в обратном направлении, от `endE` к `startE`. _graph.GetOrNewInverseRelation(relE); // Удаляем сущность-связь. _graph.DelRelation(relE); ``` # Запрос Join Сопоставляет сущности-связи с привязанными сущностями. Возвращает структуру `SubGraphMap` которая позволяет итерироваться по сопоставленным сущностями-связям. ```c# // Запросом Where получем сущности-связи, потом запросом Join сопоставляем их с конечными сущностями. // Аргумент JoinMode.End указывает что сопоставлять нужно с конечными сущностями. SubGraphMap map = _graph.GraphWorld.Where(out EventAspect relA).Join(JoinMode.End); // map.Nodes это список конечных сущностей. foreach (var endE in map.Nodes.Where(out Aspect a)) { // ... // Итерация по сопоставленным сущностям-связям. foreach (var relE in map.GetRelations(endE)) { // ... } } ``` # Пример кода Ниже приведен пример как бы могли быть реализованы системы нанесения урона взрывом и система применения урона к здоровью. Этот пример поверхностный реализации, но достаточно нагляден и демонстрирует основные функции расширения.
Использованные в примере компоненты ```c# public struct Explosion : IEcsComponent { public float damage; public float radius; } public struct Health : IEcsComponent { public float points; } public struct Transform : IEcsComponent { public Vector3 position; } // Компоненты для связей. public struct DamageEvent : IEcsComponent { public float points; } public struct KillEvent : IEcsTagComponent { } ```
```c# public class SomeExplosionHitSystem : IEcsRun, IEcsInject, IEcsInject { class EventAspect : EcsAspect { public EcsPool damageEvents = Inc; } class Aspect : EcsAspect { public EcsPool transforms = Inc; public EcsPool explosions = Inc; } EntityGraph _graph; SpatialService _spatial; public void Run() { var relA = _graph.GraphWorld.GetAspect(); foreach (var e in _graph.World.Where(out Aspect a)) { ref var transform = ref a.transforms.Get(e); ref var explosion = ref a.explosions.Get(e); // Получаем все сущности рядом со взрывом. // Реализация опущена, можно реализовать на основе Quad Tree, Spatial hashing или при помощи методов физики движка. EcsSpan targetEs = _spatial.GetEntitiesInRadius(transform.position, explosion.radius); foreach (var targetE in targetEs) { // Получаем сущность-связь от `e` к `targetE`. var relE = _graph.GetOrNewRelation(e, targetE); // Создаем событие нанесения урона. ref var damageEvent = ref relA.damageEvents.TryAddOrGet(relE); damageEvent.points = explosion.damage; } } } public void Inject(EntityGraph obj) => _graph = obj; public void Inject(SpatialService obj) => _spatial = obj; } ``` ```c# public class SomeApplyDamageSystem : IEcsRun, IEcsInject { class EventAspect : EcsAspect { public EcsPool damageEvents = Inc; public EcsTagPool killEvents = Opt; } class Aspect : EcsAspect { public EcsPool healths = Inc; } EntityGraph _graph; public void Run() { // Запрос сущностей с DamageEvent и запрос Join для них. SubGraphMap map = _graph.GraphWorld.Where(out EventAspect relA).Join(JoinMode.End); // Фильтруем конечные сущности наа наличие Health и итерируемся по ним. foreach (var endE in map.Nodes.Where(out Aspect a)) { ref var health = ref a.healths.Get(endE); bool isAlive = health.points > 0; foreach (var relE in map.GetRelations(endE)) { ref var damage = ref relA.damageEvents.Get(relE); health.points -= damage.points; if (isAlive && health.points <= 0) { // Добавляем в сущность связь тег сигнализирующий что // источник урона так же убил сущность. relA.killEvents.TryAdd(relE); } } } } public void Inject(EntityGraph obj) => _graph = obj; } ```