DragonECS-Graphs/README-RU.md

Графы сущностей для DragonECS

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

Реализация отношений сущностей в виде графа. Связывающие ребра графа представлены в виде сущностей, что позволяет создавать отношения вида многие ко многим, а с помощью компонентной композиции можно настраивать вид этих отношений.

Warning

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

Оглавление

• Установка
• Инициализация

Установка

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

Окружение

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

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

Опционально:

• Игровые движки с C#: Unity, Godot, MonoGame и т.д.

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

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

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

• Unity-модуль

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

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

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

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

Граф

Ключевой класс в котором хранится информация об отношениях. Графу требуется 2 мира: обычный мир и мир для сущностей-связей. Пример создания EntityGraph:

// Обычный мир.
_world = new EcsDefaultWorld();
// EcsGraphWorld специальный тип мира для сущностей-связей,
// но может использоваться любой другой тип мира.
_graphWorld = new EcsGraphWorld();
// Создание EntityGraph связывающий эти два мира.
EntityGraph graph = _world.CreateGraph(_graphWorld);

_pipeline = EcsPipeline.New()
    // ...
    // Далее миры и граф можно внедрить в системы.
    .Inject(_world, _graphWorld, graph)
    // ...
    .Build()

Для обычных сущностей и для сущностей-связей может использовать один общий мир:

_world = new EcsDefaultWorld();
// Создание EntityGraph завязанный на одном мире.
EntityGraph graph = _world.CreateGraph();

Сущность-связь

Как и обычная сущность, но регистрируется и создается в EntityGraph. Предназначена для данных об отношении двух сущностей.

Отношения имеют направление, поэтому чтобы разделять сущности, далее будет использованы понятия: начальная сущность(Start Entity) от нее исходит сущность-связъ(Relation Entity) к конечной сущности(End Entity). Начальная и конечная сущность это сущности-узлы(Node Entity).

(Start Entity) ── (Relation Entity) ─》(End Entity)

Пример работы с связями:

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

// Запросом 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))
    {
        // ...
    }
}

Пример кода

Ниже приведен пример как бы могли быть реализованы системы нанесения урона взрывом и система применения урона к здоровью. Этот пример поверхностный реализации, но достаточно нагляден и демонстрирует основные функции расширения.

Использованные в примере компоненты

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 { }

public class SomeExplosionHitSystem : IEcsRun, IEcsInject<EntityGraph>, IEcsInject<SpatialService>
{
    class EventAspect : EcsAspect
    {
        public EcsPool<DamageEvent> damageEvents = Inc;
    }
    class Aspect : EcsAspect
    {
        public EcsPool<Transform> transforms = Inc;
        public EcsPool<Explosion> explosions = Inc;
    }
    EntityGraph _graph;
    SpatialService _spatial;

    public void Run()
    {
        var relA = _graph.GraphWorld.GetAspect<EventAspect>();
        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;
}

public class SomeApplyDamageSystem : IEcsRun, IEcsInject<EntityGraph>
{
    class EventAspect : EcsAspect
    {
        public EcsPool<DamageEvent> damageEvents = Inc;
        public EcsTagPool<KillEvent> killEvents = Opt;
    }
    class Aspect : EcsAspect
    {
        public EcsPool<Health> 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;
}