Entity Component System

Hi Folks 🙂

In this article I want to talk about the Entity-Component-System (ECS). You can find a lot of information about the matter in the internet so I am not going to deep into explanation here, but talking more about my own implementation.

First things first. You will find the full source code of my ECS in my github repository.

An Entity-Component-System – mostly encountered in video games – is a design pattern which allows you great flexibility in designing your overall software architecture[1]. Big companies like Unity, Epic or Crytek in-cooperate this pattern into their frameworks to provide a very rich tool for developers to build their software with. You can checkout these posts to follow a broad discussion about the matter[2,3,4,5].

If you have read the articles I mentioned above you will notice they all share the same goal: distributing different concerns and tasks between Entities, Components and Systems. These are the three big players in this pattern and are fairly loose coupled. Entities are mainly used to provide a unique identifier, make the environment aware of the existence of a single individual and function as a sort of root object that bundles a set of components. Components are nothing more than container objects that do not possess any complex logic. Ideally they are simple plain old data objects (POD’s). Each type of a component can be attached to an entity to provide some sort of a property. Let’s say for example a “Health-Component” can be attached to an entity to make it mortal by giving it health, which is not more than an integer or floating point value in memory.

Up to this point most of the articles I came across agree about the purpose and use of entity and component objects, but for systems opinions differ. Some people suggest that systems are only aware of components. Furthermore some say for each type of component there should be a system, e.g. for “Collision-Components” there is a “Collision-System”, for “Health-Components” there is a “Health-System” etc. This approach is kind of rigid and does not consider the interplay of different components. A less restrictive approach is to let different systems deal with all components they should be concerned with. For instance a “Physics-Systems” should be aware of “Collision-Components” and “Rigidbody-Components”, as both probably contain necessary information regarding physics simulation. In my humble opinion systems are “closed environments”. That is, they do not take ownership of entities nor components. They do access them through independent manager objects, which in turn will take care of the entities and components life-cycle.

This raises an interesting question: how do entities, components and systems communicate with each other, if they are more or less independent of each other? Depending on the implementation the answer differs. As for the implementation I am going to show you, the answer is event sourcing[6]. Events are distributed through an “Event-Manager” and everyone who is interested in events can listen to what the manager has to say. If an entity or system or even a component has an important state change to communicate, e.g. “position changed” or “player died”, it can tell the “Event-Manager”. He will broadcast the event and all subscriber for this event will get notified. This way everything can be interconnected.

Well I guess the introduction above got longer than I was actually planning to, but here we are 🙂 Before we are going to dive deeper into the code, which is C++11 by the way, I will outline the main features of my architecture:

  • memory efficiency – to allow a quick creation and removal of entity, component and system objects as well as events I could not rely on standard new/delete managed heap-memory. The solution for this was of course a custom memory allocator.
  • logging – to see what is going on I used log4cplus[7] for logging.
  • scalable – it is easy to implement new types of entities, components, systems and events without any preset upper limit except your system’s memory
  • flexible – no dependencies exist between entities, components and systems (entities and components sure do have a sort of dependency, but do not contain any pointer logic of each other)
  • simple object lookup/access – easy retrieval of entity objects and there components through an EntityId or a component-iterator to iterate over all components of a certain type
  • flow control – systems have priorities and can depend on each other, therefore a topological order for their execution can be established
  • easy to use – the library can be easily in cooperate into other software; only one include.

The following figure depicts the overall architecture of my Entity-Component-System:

Figure-01: ECS Architecture Overview (ECS.dll).

As you can see there are four different colored areas in this picture. Each area defines a modular piece of the architecture. At the very bottom – actually in the picture above at the very top; it should be upside down – we got the memory management and the logging stuff (yellow area). This first-tier modules are dealing with very low-level tasks. They are used by the second-tier modules in the Entity-Component-System (blue area) and the event sourcing (red area). These guys mainly deal with object management tasks. Sitting on top is the third-tier module, the ECS_Engine (green area). This high-level global engine object orchestrates all second-tier modules and takes care of the initialization and destruction. All right, this was a short and very abstract overview now let’s get more into the details.

Memory Manager

Let’s start with the Memory-Manager. It’s implementation is based on an article[8] I have found on gamedev.net. The idea is to keep heap-memory allocations and releases to an absolute minimum. Therefore only at application start a big chuck of system-memory is allocated with malloc. This memory now will be managed by one or more custom allocator. There are many types of allocators[9] ( linear, stack, free list…) and each one of them has it’s pro’s and con’s (which I am not going to discuss here). But even if they internally work in a different way they all share a common public interface:

class Allocator
          virtual void* allocate(size_t size) = 0;
          virtual void free(void* p) = 0;

The code snippet above is not complete, but outlines the two major public methods each concrete allocator must provide:

  1. allocate – which allocates a certain amount of bytes and returns the memory-address to this chunk and
  2. free – to de-allocates a previously allocated chuck of memory given it’s address.

Now with that said, we can do cool stuff like chaining-up multiple allocators like that:

Figure-02: Custom allocator managed memory.

As you can see, one allocator can get it’s chunk of memory – that it is going to manage – from another (parent) allocator, which in turn could get it’s memory from another allocator and so on. That way you can establish different memory management strategies.
For the implementation of my ECS I provide a root stack-allocator that get’s an initial allocated chuck of 1GB system-memory. Second-tier modules will allocate as much memory as they need from this root allocator and only will free it when the application get’s terminated.

Figure-03: Possible distribution of global memory.

Figure-03 shows how the global memory could be distributed among the second-tier modules: “Global-Memory-User A” could be the Entity-Manager, “Global-Memory-User B” the Component-Manager and “Global-Memory-User C” the System-Manager.


I am not going to talk too much about logging as I simply used log4cplus[7] doing this job for me. All I did was defining a Logger base class hosting a log4cplus::Logger object and a few wrapper methods forwarding simple log calls like “LogInfo()”, “LogWarning()”, etc.

Entity-Manager, IEntity, Entity and Co.

Okay now let’s talk about the real meat of my architecture; the blue area in Figure-01. You may have noticed the similar setup between all manager objects and their concerning classes. Have a look at the EntityManager, IEntity and Entity classes for example. The EntityManger class is supposed to manage all entity objects during application run-time. This includes tasks like creating, deleting and accessing existing entity objects. IEntity is an interface class and provides the very basic traits of an entity object, such as an object-identifier and (static-)type-identifier. It’s static because it won’t change after program initialization. This type-identifier is also consistent over multiple application runs and may only change, if source code was modified.

class IEntity
    // code not complete!
EntityId m_Id;

        virtual ~IEntity();

        virtual const EntityTypeId GetStaticEntityTypeID() const = 0;

        inline const EntityId GetEntityID() const { return this->m_Id; }

The type-identifier is an integer value and varies for each concrete entity class. This allows us to check the type of an IEntity object at run-time. Last but not least comes the Entity template class.

class Entity : public IEntity
    // code not complete!

    void operator delete(void*) = delete;
    void operator delete[](void*) = delete;

    static const EntityTypeId STATIC_ENTITY_TYPE_ID;
Entity() {}
    virtual ~Entity() {}

    virtual const EntityTypeId GetStaticEntityTypeID() const override { return STATIC_ENTITY_TYPE_ID; }

// constant initialization of entity type identifier
const EntityTypeId Entity::STATIC_ENTITY_TYPE_ID = util::Internal::FamilyTypeID::Get();

This class’s soul purpose is the initialization of the unique type-identifier of a concrete entity class. I made use of two facts here: first constant initialization[10] of static variables and second the nature of how template classes work. Each Version of the template class Entity will have its own static variable STATIC_ENTITY_TYPE_ID. Which in turn will be guaranteed to be initialized before any dynamic initialization happens. The term “util::Internal::FamilyTypeID::Get()” is used to implement a sort of type counter mechanism. It internally increments a counter every time it gets called with a different T, but always returns the same value when called with the same T again. I am not sure if that patter has a special name, but it is pretty cool 🙂 At this point I also got ride of the delete and delete[] operator. This way I made sure nobody would accidentally call these guys. This also – as long as your compiler is smart enough – would give you a warning when trying to use the new or new[] operator of entity objects as their counterparts are gone. These operators are not intended to be used since the EntityManager class will take care of all this. Alright, let’s summarize what we just learned. The manager class provides basic functionality such as creating, deleting and accessing objects. The interface class functions as the very root base class and provides an unique object-identifier and type-identifier. The template class ensures the correct initialization of the type-identifier and removes the delete/delete[] operator. This very same pattern of a manager, interface and template class is used for components, systems and events as well. The only, but important, thing these groups differ, is the way manger classes store and access their objects.

Let’s have a look at the EntityManager class first. Figure-04 shows the overall structure of how things are stored. 


Figure-04: Abstract view of EntityManager class and it’s object storage.

When creating a new entity object one would use the EntityManager::CreateEntity<T>(args…) method. This public method first takes a template parameter which is the type of the concrete entity to be created. Secondly this method takes in an optional amount of parameters (can be empty) which are forwarded to the constructor of T. Forwarding  these parameters happens through a variadic template[11]. During creation the following things happen internally …

  1. The ObjectPool[12] for entity objects of type T will be acquired, if this pool does not exists a new one will be created
  2. New memory will be allocated from this pool; just enough to store the T object
  3. Before actually calling the constructor of T, a new EntityId is acquired from the manager. This id will be stored along with the before allocated memory into a look-up table, this way we can look-up the entity instance later with that id
  4. Next the C++ in-placement new operator[13] is called with the forwarded args… as input to create a new instance of T
  5. finally the method returns the entity’s identifier.

After a new instance of an entity object got created you can get access to it via it’s unique object identifier (EntityId) and EntityManager::GetEntity(EntityId id). To destroy an instance of an entity object one must call the EntityManager::DestroyEntity(EntityId id) method.

The ComponentManager class works in the same way plus one extension. Besides the object pools for storing all sorts of components it must provide an additional mechanism for linking components to their owning entity objects. This constraint results in a second look-up step: first we check if there is an entry for a given EntityId, if there is one we will check if this entity has a certain type of component attached by looking it up in a component-list.

Figure-05: Component-Manager object storage overview.

Using the ComponentManager::CreateComponent(EntityId id, args…) method allows us to add a certain component to an entity. With ComponentManager::GetComponent(EntityId id) we can access the entity’s components, where T specifies what type of component we want to access. If the component is not present nullptr is returned. To remove a component from an entity one would use the ComponentManager::RemoveComponent(EntityId id) method. But wait there is more. Another way of accessing components is using the ComponentIterator. This way you can iterate over all existing components of a certain type T. This might be handy if a system like the “Physics-System” wants to apply gravity to all “Rigidbody-Components”.

The SystemManager class does not have any fancy extras for storing and accessing systems. A simple map is used to store a system along with it’s type-identifier as the key.

The EventManager class uses a linear-allocator that manages a chunk of memory. This memory is used as an event buffer. Events are stored into that buffer and dispatched later. Dispatching the event will clear the buffer so new events can be stored. This happens at least once every frame.

Figure-06: Recap ECS architecture overview

I hope at this point you got a somewhat idea how things work in my ECS. If not, no worries, have a look at Figure-06 and let’s recap. You can see the EntityId is quite important as you will use it to access a concrete entity object instance and all it’s components. All components know their owner, that is, having a component object at hand you can easily get the entity by asking the EntityManager class with the given owner-id of that component. To pass an entity around you would never use it’s pointer directly, but you can use events in combination with the EntityId. You could create a concrete event, let’s say “EntityDied” for example, and this event (which must be a plain old data object) has a member of type EntityId. Now to notify all event listeners (IEventListener) – which could be Entities, Components or Systems – we use EventManager::SendEvent(entityId). The event receiver on the other side now can use the provided EntityId and ask the EntityManager class to get the entity object or the ComponentManager class to get a certain component of that entity. The reason for that detour is simple, at any point while running the application an entity or one of it’s components could be deleted by some logic. Because you won’t clutter your code by extra clean-up stuff you rely on this EntityId. If the manager returns nullptr for that EntityId, you will know that an entity or component does no longer exists. The red square btw. is corresponding to the one in Figure-01 and marks the boundaries of the ECS.

More about Systems

In this section I want to talk a little more about systems. You may remember what I have claimed in the beginning of this post: “In my humble opinion systems are “closed environments” [..]”. The motivation behind this statement is, that you could take any game you can image and identify its core mechanics. Now you take this mechanics and treat them as black-boxes. Each black-box may need zero or multiple inputs to accomplish its task and can produce zero or multiple outputs in return.

Figure-07: System In- and Outputs.

System inputs can be of any kind. It can be a file stream, a component iterator of type T, an array of data that got filled up as the system was handling events from the last processed frame. In a systems update cycle it will consume its input and may produce an output. An output might be an event, a transformation of the given input or a newly created resource. From the picture above you may noticed that there can be dependencies between systems, that is, a system might depend on the output of another system (in the example above system C needs the output A0 from system A and B0 from system B to operate). One thing that is important to point out here is that at anytime a system must be guaranteed to have exclusive access to its input. Looking at Figure-07 again you can see system A and B both share the same input source. In a multi-threaded environment systems may run in parallel, which would boost performance greatly. If systems do not share the same input there is no problem updating them in parallel, but in our case we need to determine if one of the systems wants to alter the input, if true there might be a dependency a developer should fix. If both systems only read the input we are fine. Ok enough talk let’s have a look at the code.

class ECS_API ISystem
    friend class SystemManager;


    /// Summary:	Duration since last system update in milliseconds.
    f32			m_TimeSinceLastUpdate;
    SystemPriority	m_Priority;

    /// Summary:	The system update interval.
    /// A negative value means system should update each time the engine receives an update.
    f32			m_UpdateInterval;

    u8			m_Enabled	: 1;
    u8			m_NeedsUpdate	: 1;
    u8			m_Reserved	: 6;

// ...

    virtual void PreUpdate(f32 dt) = 0;
    virtual void Update(f32 dt)	= 0;
    virtual void PostUpdate(f32 dt) = 0;

class System : public ISystem
// ...

void AddDependencies(Dependencies&&... dependencies)
this->m_SystemManagerInstance->AddSystemDependency(this, std::forward(dependencies)...);
// ...

As always the code above is not complete, but outlines the main public interfaces: PreUpdate, Update, PostUpdate and AddDependencies. The update functions will be called in the order above, first the PreUpdate of each system is called, after the Update and last the PostUpdate function. The main logic of a system should always go into the Update method. The PreUpdate method gives each system a chance to run some setup or to prepare for the output of a system generated in the Update method. The PostUpdate can be used for clean up. Another very important method is the AddDependencies method. This method can be called on systems and add systems they are depending on. The SystemManager will be notified and it updates the internal work order of all systems. This work order is determined by topological sorting [14]. Topological sorting is an algorithm that can be used to determine an order of what should be done first, then second and so on. Another way to establish some sort of order is by introducing system priorities. Systems with a higher priority should be updated first. Systems with the same priority are treated in a FIFO manner. Beside a well defined work order there are two more features: a systems update frequency and enabled/disabled state. The update frequency determines how often a system should be, e.g. every frame or every 5 or 10 seconds? This is a great way to reduce the work load for processing a frame. For instance AI logic might not be required to be updated each frame, but rather every 2 seconds or so. Last but not least systems can be disabled. Imagine you have different game states, like in “In-Game Menu”, “Lobby” or “Running Game” state and each one of them uses a different set of systems. Instead of fully removing a system and re-create is later on when changing a game state you would disable and enable them. For my implementation I also introduced a SystemWorkStateMask, which resembles a bitmask holding a snapshot of the current enabled and disabled systems. One could take a snapshot before changing the game state and therefore the system states. When return to the old game state later on, you only have to use the previously saved work state mask.

The Engine object

To make things a little bit more comfortable I created an engine object. The engine object ensures an easy integration and usage in client software. On client side one only has to include the “ECS/ECS.h” header and call the ECS::Initialize() method. Now a static global engine object will be initialized (ECS::ECS_Engine) and can be used at client side to get access to all the manager classes. Furthermore it provides  a SendEvent method for broadcasting events and an Update method, which will automatically dispatch all events and update all systems. The ECS::Terminate() should be called before exiting the main program. This will ensure that all acquired resources will be freed. The code snippet bellow demonstrates the very basic usage of the ECS’s global engine object.


int main(int argc,char* argv[])
    // initialize global 'ECS_Engine' object

    const float DELTA_TIME_STEP = 1.0f / 60.0f; // 60hz

    bool bQuit = false;

    // run main loop until quit
   while(bQuit == false)
       // Update all Systems, dispatch all buffered events,
       // remove destroyed components and entities ...
       ECS::ECS_Engine-&gt;Update<span id="mce_SELREST_start" style="overflow:hidden;line-height:0;"></span>(DELTA_TIME_STEP);

       // more logic ...

   // destroy global 'ECS_Engine' object
   return 0;


The Entity-Component-System described in this article is fully functional and ready to use. But as usual there are certainly a few thinks to improve. The following list outlines just a few ideas that I came up with:

  • Make it thread-safe,
  • Run each system or a group of systems in threats w.r.t. to their topological order,
  • Refactor event-sourcing and memory management and include them as modules,
  • serialization,
  • profiling

I hope this article was helpful and you enjoyed reading it as much as I did writing it 🙂 If you want to see my ECS in action check out this demo:

The BountyHunter demo makes heavily use of the ECS and demonstrates the strength of this pattern. If you want to know how?, have a look at this post.

So far …




5 thoughts on “Entity Component System

  1. Very nice implementation. Especially the allocator stuff. ECS specifically though, for optimization purposes I suppose you could have the entity simply as an integer, nothing else (using EntityId = ui32/64;). Having a virtual function for something like that will hurt performance on the long run. Just giving ideas..


  2. Have you considered or investigated the performance implications of the virtual function calls?

    I’m attempting to implement my own ECS but nearly all examples I find use abstract base classes with virtual update functions that are called frequently.

    The other side of the coin seems to be template metaprogramming which is hard to understand.


    1. Hi mate,
      thanks for posting 🙂 i did not have run any investigations regarding performance and virtual functions. But looking at this post: https://eli.thegreenplace.net/2013/12/05/the-cost-of-dynamic-virtual-calls-vs-static-crtp-dispatch-in-c it might be well worth it applying CRTP instead of using virtual functions. I did run the sample code from this guys post and could not see much performance gain. In my case CRTP was ~0.1sec faster, but this may change as I did use the VS test frame work for testing.

      I agree meta-programming can be pain. But this might be overcome using pre-defined macros to setup net classes or even better code generator/editors.

      Anyway good luck with your project.



  3. This is such a fantastic project. But I am confused about one thing; In the SystemManager, all system update calls are made with the delta time value passed to `SystemManager::Update(f32)`. Shouldn’t the value passed to each system be the delta time since the last `ISystem::update(f32)` was called for that system?


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s