https://github.com/dcfapixels/dragonecs-graphs
Relations between entities for DragonECS
https://github.com/dcfapixels/dragonecs-graphs
Last synced: about 2 months ago
JSON representation
Relations between entities for DragonECS
- Host: GitHub
- URL: https://github.com/dcfapixels/dragonecs-graphs
- Owner: DCFApixels
- License: mit
- Created: 2023-06-17T06:14:43.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-03-31T04:20:24.000Z (2 months ago)
- Last Synced: 2025-03-31T05:20:29.712Z (2 months ago)
- Language: C#
- Homepage:
- Size: 149 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README-RU.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Графы сущностей для [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;
}
```