LeoEcsLite - Lightweight C# Entity Component System framework

Performance, zero/small memory allocations/footprint, no dependencies on any game engine - main goals of this project.

Important! Don't forget to use DEBUG builds for development and RELEASE builds in production: all internal error checks / exception throwing works only in DEBUG builds and eleminated for performance reasons in RELEASE.

Important! LeoEcsLite API is not tread safe and will never be! If you need multithread-processing - you should implement it on your side as part of ecs-system.

Table of content

• Socials
• Installation
  • As unity module
  • As source
• Main parts of ecs
  • Entity
  • Component
  • System
• Data sharing
• Special classes
  • EcsPool
  • EcsFilter
  • EcsWorld
  • EcsSystems
• Engine integration
  • Unity
  • Custom engine
• Projects powered by LeoECS Lite
  • With sources
• Extensions
• License
• FAQ

Socials

Installation

As unity module

This repository can be installed as unity module directly from git url. In this way new line should be added to Packages/manifest.json:

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

By default last released version will be used. If you need trunk / developing version then develop name of branch should be added after hash:

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

As source

If you can't / don't want to use unity modules, code can be cloned or downloaded as archive from releases page.

Main parts of ecs

Entity

Сontainer for components. Implemented as int:

// Creates new entity in world context.intentity=_world.NewEntity();// Any entity can be destroyed. All components will be removed first, then entity will be destroyed. world.DelEntity(entity);

Important! Entities can't live without components and will be killed automatically after last component removement.

Component

Container for user data without / with small logic inside:

structComponent1{publicintId;publicstringName;}

Components can be added / requested / removed through component pools.

System

Сontainer for logic for processing filtered entities. User class should implement IEcsInitSystem, IEcsDestroySystem, IEcsRunSystem (or other supported) interfaces:

classUserSystem:IEcsPreInitSystem,IEcsInitSystem,IEcsRunSystem,IEcsDestroySystem,IEcsPostDestroySystem{publicvoidPreInit(EcsSystemssystems){// Will be called once during EcsSystems.Init() call and before IEcsInitSystem.Init().}publicvoidInit(EcsSystemssystems){// Will be called once during EcsSystems.Init() call and after IEcsInitSystem.PreInit().}publicvoidRun(EcsSystemssystems){// Will be called on each EcsSystems.Run() call.}publicvoidDestroy(EcsSystemssystems){// Will be called once during EcsSystems.Destroy() call and before IEcsInitSystem.PostDestroy().}publicvoidPostDestroy(EcsSystemssystems){// Will be called once during EcsSystems.Destroy() call and after IEcsInitSystem.Destroy().}}

Data sharing

Instance of any custom type can be shared between all systems:

classSharedData{publicstringPrefabsPath;}
...SharedData sharedData =newSharedData{PrefabsPath="Items/{0}"};EcsSystemssystems=newEcsSystems(world,sharedData);systems.Add(newTestSystem1()).Init();
...
class TestSystem1 :IEcsInitSystem{publicvoidInit(EcsSystemssystems){SharedDatashared=systems.GetShared<SharedData>();stringprefabPath=string.Format(shared.PrefabsPath,123);// prefabPath = "Items/123" here.}}

Special classes

EcsPool

Container for components, provides api for adding / requesting / removing components on entity:

intentity=world.NewEntity();EcsPool<Component1>pool=world.GetPool<Component1>();// Add() adds component to entity. If component already exists - exception will be raised in DEBUG.refComponent1c1=refpool.Add(entity);// Get() returns exist component on entity. If component does not exists - exception will be raised in DEBUG.refComponent1c1=refpool.Get(entity);// Del() removes component from entity. If it was last component - entity will be removed automatically too.pool.Del(entity);

Important! After removing component will be pooled and can be reused later. All fields will be reset to default values automatically.

EcsFilter

Container for keeping filtered entities with specified component list:

classWeaponSystem:IEcsInitSystem,IEcsRunSystem{publicvoidInit(EcsSystemssystems){// We want to get default world instance...EcsWorldworld=systems.GetWorld();// and create test entity...intentity=world.NewEntity();// with "Weapon" component on it.varweapons=world.GetPool<Weapon>();weapons.Add(entity);}publicvoidRun(EcsSystemssystems){EcsWorldworld=systems.GetWorld();// We want to get entities with "Weapon" and without "Health".// You can cache this filter somehow if you want.varfilter=world.Filter<Weapon>().Exc<Health>().End();// We want to get pool of "Weapon" components.// You can cache this pool somehow if you want.varweapons=world.GetPool<Weapon>();foreach(intentityinfilter){refWeaponweapon=refweapons.Get(entity);weapon.Ammo=System.Math.Max(0,weapon.Ammo-1);}}}

Additional constraints can be added with Inc<>() / Exc<>() methods.

Important: Any filter supports any amount of components, include and exclude lists can't intersect and should be unique.

EcsWorld

Root level container for all entities / components, works like isolated environment.

Important: Do not forget to call EcsWorld.Destroy() method if instance will not be used anymore.

EcsSystems

Group of systems to process EcsWorld instance:

classStartup:MonoBehaviour{EcsWorld_world;EcsSystems_systems;voidStart(){// create ecs environment._world=newEcsWorld();_systems=newEcsSystems(_world).Add(newWeaponSystem());_systems.Init();}voidUpdate(){// process all dependent systems._systems?.Run();}voidOnDestroy(){// destroy systems logical group.if(_systems!=null){_systems.Destroy();_systems=null;}// destroy world.if(_world!=null){_world.Destroy();_world=null;}}}

Important: Do not forget to call EcsSystems.Destroy() method if instance will not be used anymore.

Engine integration

Unity

Tested on unity 2020.3 (but not dependent on it) and contains assembly definition for compiling to separate assembly file for performance reason.

Not ready yet.

Custom engine

C#7.3 or above required for this framework.

Code example - each part should be integrated in proper place of engine execution flow.

usingLeopotam.EcsLite;classEcsStartup{EcsWorld_world;EcsSystems_systems;// Initialization of ecs world and systems.voidInit(){_world=newEcsWorld();_systems=newEcsSystems(_world);_systems// register additional worlds here.// .AddWorld (customWorldInstance, "events")// register your systems here, for example:// .Add (new TestSystem1 ())// .Add (new TestSystem2 ())// register components for removing here// position in registration is important,// should be after all AddWorld() registration, for example:// .DelHere<TestComponent1> ()// .DelHere<TestComponent2> ("events").Init();}// Engine update loop.voidUpdateLoop(){_systems?.Run();}// Cleanup.voidDestroy(){if(_systems!=null){_systems.Destroy();_systems=null;}if(_world!=null){_world.Destroy();_world=null;}}}

Projects powered by LeoECS Lite

With sources

• "3D Platformer"

Extensions

• Extended filters support
• Threads support
• Unity editor integration
• Unity uGui bindings
• Unity jobs support
• UniLeo - Unity scene data converter

License

The software is released under the terms of the MIT license.

No personal support or any guarantees.

FAQ

I want to process one system at MonoBehaviour.Update() and another - at MonoBehaviour.FixedUpdate(). How can I do it?

For splitting systems by MonoBehaviour-method multiple EcsSystems logical groups should be used:

EcsSystems_update;EcsSystems_fixedUpdate;voidStart(){EcsWorldworld=newEcsWorld();_update=newEcsSystems(world).Add(newUpdateSystem());_update.Init();_fixedUpdate=newEcsSystems(world).Add(newFixedUpdateSystem());_fixedUpdate.Init();}voidUpdate(){_update.Run();}voidFixedUpdate(){_fixedUpdate.Run();}

I copy&paste my reset components code again and again. How can I do it in other manner?

If you want to simplify your code and keep reset/init code at one place, you can setup custom handler to process cleanup / initialization for component:

structMyComponent:IEcsAutoReset<MyComponent>{publicintId;publicobjectLinkToAnotherComponent;publicvoidAutoReset(refMyComponentc){c.Id=2;c.LinkToAnotherComponent=null;}}

This method will be automatically called for brand new component instance and after component removing from entity and before recycling to component pool.

Important: With custom AutoReset behaviour there are no any additional checks for reference-type fields, you should provide correct cleanup/init behaviour without possible memory leaks.

I use components as events that work only one frame, then remove it at last system in execution sequence. It's boring, how can I automate it?

If you want to remove one-frame components without additional custom code, you can register them at EcsSystems:

structMyOneFrameComponent{}EcsSystems_update;voidStart(){EcsWorldworld=newEcsWorld();_update=newEcsSystems(world);_update.Add(newCalculateSystem()).Add(newUpdateSystem()).DelHere<MyOneFrameComponent>().Init();}voidUpdate(){_update.Run();}

important: All one-frame components should be registered with DelHere() after all worlds registration through AddWorld(). Important: All one-frame components with specified type will be removed at position in execution flow where this component was registered with DelHere() call.

I want to keep references to entities in components, but entity can be killed at any system and I need protection from reusing the same ID. How can I do it?

For keeping entity somewhere you should pack it to special EcsPackedEntity or EcsPackedEntityWithWorld types:

EcsWorldworld=newEcsWorld();intentity=world.NewEntity();EcsPackedEntitypacked=world.PackEntity(entity);EcsPackedEntityWithWorldpackedWithWorld=world.PackEntityWithWorld(entity);
...if(packed.Unpack(world,outintunpacked)){// unpacked is valid and can be used.}if(packedWithWorld.Unpack(outEcsWorldunpackedWorld,outintunpackedWithWorld)){// unpackedWithWorld is valid and can be used.}

I want to add some reactive behaviour on world changes, how I can do it?

You can use LEOECSLITE_WORLD_EVENTS definition to enable custom event listeners support on worlds:

classTestWorldEventListener:IEcsWorldEventListener{publicvoidOnEntityCreated(intentity){// entity created - raises on world.NewEntity().}publicvoidOnEntityChanged(intentity){// entity changed - raises on pool.Add() / pool.Del().}publicvoidOnEntityDestroyed(intentity){// entity destroyed - raises on world.DelEntity() or last component removing.}publicvoidOnFilterCreated(EcsFilterfilter){// filter created - raises on world.Filter().End() for brand new filter.}publicvoidOnWorldResized(intnewSize){// world resized - raises on world/pools resizing when no room for entity at world.NewEntity() call.}publicvoidOnWorldDestroyed(EcsWorldworld){// world destroyed - raises on world.Destroy().}}
...var world =newEcsWorld();varlistener=newTestWorldEventListener();world.AddEventListener(listener);