Leopotam.Ecs 1.0.1

LeoECS - Легковесный C# Entity Component System фреймворк

Производительность, нулевые или минимальные аллокации, минимизация использования памяти, отсутствие зависимостей от любого игрового движка - это основные цели данного фреймворка.

ВАЖНО! РАЗРАБОТКА ДАННОГО ПРОЕКТА ПРЕКРАЩЕНА, ВМЕСТО НЕГО СЛЕДУЕТ ИСПОЛЬЗОВАТЬ EcsProto или EcsLite.

ВАЖНО! Не забывайте использовать DEBUG-версии билдов для разработки и RELEASE-версии билдов для релизов: все внутренние проверки/исключения будут работать только в DEBUG-версиях и удалены для увеличения производительности в RELEASE-версиях.

ВАЖНО! LeoEcs-фрейморк не потокобезопасен и никогда не будет таким! Если вам нужна многопоточность - вы должны реализовать ее самостоятельно и интегрировать синхронизацию в виде ecs-системы.

Содержание

• Социальные ресурсы
• Установка
  • В виде unity модуля
  • В виде исходников
• Основные типы
  • Компонент
  • Сущность
  • Система
• Инъекция данных
• Специальные типы
  • EcsFilter<T>
  • EcsWorld
  • EcsSystems
• Интеграция с движками
  • Unity
  • Кастомный движок
• Статьи
• Проекты, использующие LeoECS
  • С исходниками
• Расширения
• Лицензия
• ЧаВо

Социальные ресурсы

👁 discord

Установка

В виде unity модуля

Поддерживается установка в виде unity-модуля через git-ссылку в PackageManager или прямое редактирование Packages/manifest.json:

"com.leopotam.ecs": "https://github.com/Leopotam/ecs.git",

По умолчанию используется последняя релизная версия. Если требуется версия "в разработке" с актуальными изменениями - следует переключиться на ветку develop:

"com.leopotam.ecs": "https://github.com/Leopotam/ecs.git#develop",

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

Код так же может быть склонирован или получен в виде архива со страницы релизов.

Основные типы

Компонент

Является контейнером для данных пользователя и не должен содержать логику (допускаются минимальные хелперы, но не куски основной логики):

struct WeaponComponent {
 public int Ammo;
 public string GunName;
}

Сущность

Сама по себе ничего не значит и не существует, является исключительно контейнером для компонентов. Реализована как EcsEntity:

// NewEntity() используется для создания новых сущностей в контексте мира.
EcsEntity entity = _world.NewEntity ();

// Get() возвращает существующий на сущности компонент. Если компонент не существовал - он будет добавлен автоматически.
// Следует обратить внимание на "ref" - компоненты должны обрабатываться по ссылке.
ref Component1 c1 = ref entity.Get<Component1> ();
ref Component2 c2 = ref entity.Get<Component2> ();

// Del() удаляет компонент с сущности. Если это был последний компонент - сущность будет удалена автоматически. Если компонент не существовал - ошибки не будет.
entity.Del<Component2> ();

// Replace() выполняет замену компонента новым экземпляром. Если старый компонент не существовал - новый будет добавлен без ошибки.
WeaponComponent weapon = new WeaponComponent () { Ammo = 10, GunName = "Handgun" };
entity.Replace (weapon);

// Replace() позволяет выполнять "чейнинг" создания компонентов:
EcsEntity entity2 = world.NewEntity ();
entity2.Replace (new Component1 { Id = 10 }).Replace (new Component2 { Name = "Username" });

// Любая сущность может быть скопирована вместе с компонентами:
EcsEntity entity2Copy = entity2.Copy ();

// Любая сущность может "передать" свои компоненты другой сущности (сама будет уничтожена):
var newEntity = world.NewEntity ();
entity2Copy.MoveTo (newEntity); // все компоненты с "entity2Copy" переместятся на "newEntity", а "entity2Copy" будет удалена.

// Любая сущность может быть удалена, при этом сначала все компоненты будут автоматически удалены и только потом энтити будет считаться уничтоженной. 
entity.Destroy ();

ВАЖНО! Сущности не могут существовать без компонентов и будут автоматически уничтожаться при удалении последнего компонента на них.

Система

Является контейнером для основной логики для обработки отфильтрованных сущностей. Существует в виде пользовательского класса, реализующего как минимум один из IEcsInitSystem, IEcsDestroySystem, IEcsRunSystem (и прочих поддерживаемых) интерфейсов:

class UserSystem : IEcsPreInitSystem, IEcsInitSystem, IEcsRunSystem, IEcsDestroySystem, IEcsPostDestroySystem {
 public void PreInit () {
 // Будет вызван один раз в момент работы EcsSystems.Init() и до срабатывания IEcsInitSystem.Init().
 }

 public void Init () {
 // Будет вызван один раз в момент работы EcsSystems.Init() и после срабатывания IEcsPreInitSystem.PreInit().
 }
 
 public void Run () {
 // Будет вызван один раз в момент работы EcsSystems.Run().
 }

 public void Destroy () {
 // Будет вызван один раз в момент работы EcsSystems.Destroy() и до срабатывания IEcsPostDestroySystem.PostDestroy().
 }

 public void PostDestroy () {
 // Будет вызван один раз в момент работы EcsSystems.Destroy() и после срабатывания IEcsDestroySystem.Destroy().
 }
}

Инъекция данных

Все поля ecs-систем, совместимые c EcsWorld и EcsFilter<T> будут автоматически инициализированы валидными экземплярами соответствующих типов:

class HealthSystem : IEcsSystem {
 // Поля с авто-инъекцией.
 EcsWorld _world;
 EcsFilter<WeaponComponent> _weaponFilter;
}

Экземпляр любого кастомного типа (класса) может быть инъецирован с помощью метода EcsSystems.Inject():

class SharedData {
 public string PrefabsPath;
}
...
SharedData sharedData = new SharedData { PrefabsPath = "Items/{0}" };
EcsSystems systems = new EcsSystems (world);
systems
 .Add (new TestSystem1 ())
 .Inject (sharedData)
 .Init ();

Каждая система будет просканирована на наличие полей, совместимых по типу с последующей инъекцией:

class TestSystem1 : IEcsInitSystem {
 // Поле с авто-инъекцией.
 SharedData _sharedData;
 
 public void Init() {
 var prefabPath = string.Format (_sharedData.Prefabspath, 123);
 // prefabPath = "Items/123" к этому моменту.
 } 
}

ВАЖНО! Для инъекции подходят только нестатичные public/private-поля конечного класса системы, либо public/protected-поля базовых классов. Все остальные поля будут проигнорированы!

Специальные типы

EcsFilter<T>

Является контейнером для хранения отфильтрованных сущностей по наличию или отсутствию определенных компонентов:

class WeaponSystem : IEcsInitSystem, IEcsRunSystem {
 // Поля с авто-инъекцией.
 EcsWorld _world;
 // Мы хотим получить все сущности с компонентом "WeaponComponent"
 // и без компонента "HealthComponent".
 EcsFilter<WeaponComponent>.Exclude<HealthComponent> _filter;

 public void Init () {
 _world.NewEntity ().Get<WeaponComponent> ();
 }

 public void Run () {
 foreach (int i in _filter) {
 // Сущность, которая точно содержит компонент "WeaponComponent".
 ref EcsEntity entity = ref _filter.GetEntity (i);

 // Get1() позволяет получить доступ по ссылке на компонент,
 // указанный первым в списке ограничений фильтра ("WeaponComponent").
 ref WeaponComponent weapon = ref _filter.Get1 (i);
 weapon.Ammo = System.Math.Max (0, weapon.Ammo - 1);
 }
 }
}

Любые компоненты из Include-списка ограничений фильтра могут быть получены через вызовы EcsFilter.Get1(), EcsFilter.Get2() и т.д - нумерация идет в том же порядке, что и в списке ограничений.

Если в компоненте нет данных и он используется исключительно как флаг-признак для фильтрации, то компонент может реализовать интерфейс IEcsIgnoreInFilter - это поможет уменьшить потребление памяти фильтром и немного увеличить производительность:

struct Component1 { }

struct Component2 : IEcsIgnoreInFilter { }

class TestSystem : IEcsRunSystem {
 EcsFilter<Component1, Component2> _filter;

 public void Run () {
 foreach (var i in _filter) {
 // Мы можем получить компонент "Component1".
 ref var component1 = ref _filter.Get1 (i);

 // Мы не можем получить "Component2" - кеш внутри фильтра не существует и будет выкинуто исключение.
 ref var component2 = ref _filter.Get2 (i);
 }
 }
}

ВАЖНО!: Фильтры поддерживают до 6 Include-ограничений и 2 Exclude-ограничений. Чем меньше ограничений в фильтре - тем он быстрее работает.

ВАЖНО! Нельзя использовать несколько фильтров с одинаковым списком ограничений, но выставленных в разном порядке - в DEBUG-версии будет выкинуто исключение с описанием конфликтующих фильтров.

ВАЖНО! Один и тот же компонент не может быть в списках "Include" и "Exclude" одного фильтра одновременно.

EcsWorld

Является контейнером для всех сущностей и фильтров, данные каждого экземпляра уникальны и изолированы от других миров.

ВАЖНО! Необходимо вызывать EcsWorld.Destroy() у экземпляра мира если он больше не нужен.

EcsSystems

Является контейнером для систем, которыми будет обрабатываться EcsWorld-экземпляр мира:

class Startup : MonoBehaviour {
 EcsWorld _world;
 EcsSystems _systems;

 void Start () {
 // Создаем окружение, подключаем системы.
 _world = new EcsWorld ();
 _systems = new EcsSystems (_world)
 .Add (new WeaponSystem ());
 _systems.Init ();
 }
 
 void Update () {
 // Выполняем все подключенные системы.
 _systems.Run ();
 }

 void OnDestroy () {
 // Уничтожаем подключенные системы.
 _systems.Destroy ();
 // Очищаем окружение.
 _world.Destroy ();
 }
}

Экземпляр EcsSystems может быть использован как обычная ecs-система (вложена в другую EcsSystems):

// Инициализация.
EcsSystems nestedSystems = new EcsSystems (_world).Add (new NestedSystem ());

// Нельзя вызывать nestedSystems.Init() здесь,
// "rootSystems" выполнит этот вызов автоматически.
EcsSystems rootSystems = new EcsSystems (_world).Add (nestedSystems);
rootSystems.Init ();

// В цикле обновления нельзя вызывать nestedSystems.Run(),
// "rootSystems" выполнит этот вызов автоматически.
rootSystems.Run ();

// Очистка.
// Нельзя вызывать nestedSystems.Destroy() здесь,
// "rootSystems" выполнит этот вызов автоматически.
rootSystems.Destroy ();

Любая IEcsRunSystem система (включая вложенные EcsSystems) может быть включен или выключен из списка обработки:

class TestSystem : IEcsRunSystem {
 public void Run () { }
}
EcsSystems systems = new EcsSystems (_world);
systems.Add (new TestSystem (), "my special system");
systems.Init ();
var idx = systems.GetNamedRunSystem ("my special system");

// "state" будет иметь значение "true", все системы включены по умолчанию.
var state = systems.GetRunSystemState (idx);

// Выключаем систему по ее индексу.
systems.SetRunSystemState (idx, false);

Интеграция с движками

Unity

Проверено на Unity 2020.3 (не зависит от нее) и содержит asmdef-описания для компиляции в виде отдельных сборок и уменьшения времени рекомпиляции основного проекта.

Интеграция в Unity editor содержит шаблоны кода, а так же предоставляет мониторинг состояния мира.

Кастомный движок

Для использования фреймворка требуется C#7.3 или выше.

Каждая часть примера ниже должна быть корректно интегрирована в правильное место выполнения кода движком:

using Leopotam.Ecs;

class EcsStartup {
 EcsWorld _world;
 EcsSystems _systems;

 // Инициализация окружения.
 void Init () { 
 _world = new EcsWorld ();
 _systems = new EcsSystems (_world);
 _systems
 // Системы с основной логикой должны
 // быть зарегистрированы здесь, порядок важен:
 // .Add (new TestSystem1 ())
 // .Add (new TestSystem2 ())
 
 // OneFrame-компоненты должны быть зарегистрированы
 // в общем списке систем, порядок важен:
 // .OneFrame<TestComponent1> ()
 // .OneFrame<TestComponent2> ()
 
 // Инъекция должна быть произведена здесь,
 // порядок не важен:
 // .Inject (new CameraService ())
 // .Inject (new NavMeshSupport ())
 .Init ();
 }

 // Метод должен быть вызван из
 // основного update-цикла движка.
 void UpdateLoop () {
 _systems?.Run ();
 }

 // Очистка.
 void Destroy () {
 if (_systems != null) {
 _systems.Destroy ();
 _systems = null;
 _world.Destroy ();
 _world = null;
 }
 }
}

Статьи

• "Создание шутера с LeoECS. Часть 1"

• "Создание шутера с LeoECS. Часть 2"

• "Создание шутера с LeoECS. Часть 3"

• "Создание шутера с LeoECS. Часть 4"

• "Всё что нужно знать про ECS"

Проекты, использующие LeoECS

С исходниками

• "MatchTwo"

• "Bubble shooter"

• "Frantic Architect Remake"

• "Mahjong Solitaire"

• "Tetris"

  👁 alternate text is missing from this package README image
  

• "3D Platformer"

  👁 alternate text is missing from this package README image
  

• "SpaceInvaders (Guns&Bullets variation)"

• "Pacman"

• "Runner"

Расширения

• Интеграция в редактор Unity
• Поддержка Unity uGui
• Поддержка многопоточности
• Unity Physx events support

Лицензия

Фреймворк выпускается под двумя лицензиями, .

В случаях лицензирования по условиям MIT-Red не стоит расчитывать на персональные консультации или какие-либо гарантии.

ЧаВо

Я хочу знать - существовал ли компонент на сущности до вызова Get() для разной инициализации полученных данных. Как я могу это сделать?

Если не важно - существовал компонент ранее и просто нужна уверенность, что он теперь существует достаточно вызова EcsEntity.Get<T>().

Если нужно понимание, что компонент существовал ранее - это можно проверить с помощью вызова EcsEntity.Has<T>().

Я хочу одну систему вызвать в MonoBehaviour.Update(), а другую - в MonoBehaviour.FixedUpdate(). Как я могу это сделать?

Для разделения систем на основе разных методов из MonoBehaviour необходимо создать под каждый метод отдельную EcsSystems-группу:

EcsSystems _update;
EcsSystems _fixedUpdate;

void Start () {
 var world = new EcsWorld ();
 _update = new EcsSystems (world).Add (new UpdateSystem ());
 _update.Init ();
 _fixedUpdate = new EcsSystems (world).Add (new FixedUpdateSystem ());
 _fixedUpdate.Init ();
}

void Update () {
 _update.Run ();
}

void FixedUpdate () {
 _fixedUpdate.Run ();
}

Мне нравится как работает автоматическая инъекция данных, но хотелось бы часть полей исключить. Как я могу сделать это?

Для этого достаточно пометить поле системы атрибутом [EcsIgnoreInject]:

// Это поле будет обработано инъекцией.
EcsFilter<C1> _filter1;

// Это поле будет проигнорировано инъекцией.
[EcsIgnoreInject] EcsFilter<C2> _filter2;

Меня не устраивают значения по умолчанию для полей компонентов. Как я могу это настроить?

Компоненты поддерживают кастомную настройку значений через реализацию интерфейса IEcsAutoReset<>:

struct MyComponent : IEcsAutoReset<MyComponent> {
 public int Id;
 public object LinkToAnotherComponent;

 public void AutoReset (ref MyComponent c) {
 c.Id = 2;
 c.LinkToAnotherComponent = null;
 }
}

Этот метод будет автоматически вызываться для всех новых компонентов, а так же для всех только что удаленных, до помещения их в пул.

ВАЖНО! В случае применения IEcsAutoReset все дополнительные очистки/проверки полей компонента отключаются, что может привести к утечкам памяти. Ответственность лежит на пользователе!

ВАЖНО!: Компоненты, реализующие IEcsAutoReset не совместимы с вызовами entity.Replace(). Рекомендуется не использовать entity.Replace() или любые другие способы полной перезаписи компонентов.

Я использую компоненты как "события", которые живут 1 цикл, а потом удаляются в конце отдельной системой. Получается много лишнего кода, есть ли более простой способ?

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

struct MyOneFrameComponent { }

EcsSystems _update;

void Start () {
 var world = new EcsWorld ();
 _update = new EcsSystems (world);
 _update
 .Add (new CalculateSystem ())
 // Все "MyOneFrameComponent" компоненты будут
 // удалены здесь.
 .OneFrame<MyOneFrameComponent> ()
 // Здесь можно быть уверенным, что ни один
 // "MyOneFrameComponent" не существует.
 .Add (new UpdateSystem ())
 .Init ();
}

void Update () {
 _update.Run ();
}

Мне нужен больший контроль над размерами кешей, которые мир использует в момент создания. Как я могу сделать это?

Мир может быть создан с явным указанием EcsWorldConfig-конфигурации:

var config = new EcsWorldConfig () {
 // Размер по умолчанию для World.Entities.
 WorldEntitiesCacheSize = 1024,
 // Размер по умолчанию для World.Filters.
 WorldFiltersCacheSize = 128,
 // Размер по умолчанию для World.ComponentPools.
 WorldComponentPoolsCacheSize = 512,
 // Размер по умолчанию для Entity.Components (до удвоения).
 EntityComponentsCacheSize = 8,
 // Размер по умолчанию для Filter.Entities.
 FilterEntitiesCacheSize = 256,
};
var world = new EcsWorld(config);

Мне нужно больше чем 6-"Include" и 2-"Exclude" ограничений для компонентов в фильтре. Как я могу сделать это?

ВАЖНО! Это приведет к модификации исходного кода фреймворка и несовместимости с обновлениями.

Необходимо воспользоваться кодогенерацией EcsFilter классов и заменить содержимое файла EcsFilter.cs.

Я хочу добавить реактивщины и обрабатывать события изменения фильтров. Как я могу это сделать?

ВАЖНО! Так делать не рекомендуется из-за падения производительности.

Для активации этого функционала следует добавить LEOECS_FILTER_EVENTS в список директив комплятора, а затем - добавить слушатель событий:

class CustomListener: IEcsFilterListener {
 public void OnEntityAdded (in EcsEntity entity) {
 // Сущность добавлена в фильтр.
 }
 
 public void OnEntityRemoved (in EcsEntity entity) {
 // Сущность удалена из фильтра.
 }
}

class MySystem : IEcsInitSystem, IEcsDestroySystem {
 readonly EcsFilter<Component1> _filter = null;
 readonly CustomListener _listener = new CustomListener ();
 public void Init () {
 // Подписка слушателя на события фильтра.
 _filter.AddListener (_listener);
 }
 public void Destroy () {
 // Отписка слушателя от событий фильтра.
 _filter.RemoveListener (_listener);
 }
}