Entity-Component-System (ECS)

Previously, we've been building a structure of arrays (SoA) container, using a collection of players in a video game. Conceptually, this has been like a table in a database. Our parallel arrays, with names like score, and health, have been columns. Each player has been in a row in that table.

But we can only get so far with a single table. Realistic systems need multiple tables, and our systems need ways to efficiently pull data from multiple tables.

For example, let's imagine we're making a game world, full of entities with different capabilities. Some entities might need to emit audio, and some might need to show up as a "nearby" radar icon. If we added the fields to support these capabilities to our SoA, we would waste massive amounts of memory and bandwidth for entities that don't need them.

In this chapter, we are going to break our monolithic SoA apart. We will build a relational storage system that allows us to represent entities of a wide variety of types, without sacrificing the contiguous memory layout that gives us raw speed.

Let's look at how we might add optional data to our entities. We'll start with a basic EntityStorage class that uses the SoA techniques we've become accustomed to.

For now, each entity will have a name, and we'll use a simple int index to identify it:

1#pragma once
2#include <vector>
3#include <string>
4
5class EntityStorage {
6public:
7  std::vector<std::string> m_names;
8
9  int Add(std::string name) {
10    m_names.push_back(std::move(name));
11    return int(m_names.size() - 1);
12  }
13};

Let's imagine we need to implement two different systems, each requiring optional data on our entities:

1. Audio: A component containing data helpful for emitting audio. We'll assume only ~10% of entities make noise.
2. Proximity: A component used to mark which entities are close to a player. It contains data useful for the additional work we need to do with those entities, such as network synchronization. We'll assume only ~10% of entities will be close enough to need this additional data at any given time.

The Object-Oriented Approach

With object-oriented programming, we traditionally model reality using class hierarchies. We might build Player, Monster, and Foliage classes, sharing a base class like GameObject and overriding virtual methods.

We could then represent our world as an array of GameObject pointers, using runtime polymorphism to get dynamic behaviors for our optional systems:

1struct GameObject {
2  // Most entities don't need audio, but they
3  // can override this if they do
4  virtual void PlayAudio() {}
5  
6  // ...
7};
8
9struct World {
10  void ProcessAudio() {
11    for (auto Entity : Entities) {
12      // Pointer chasing
13      Entity->PlayAudio();
14    }
15  }
16
17  std::vector<GameObject*> Entities;
18};

This is elegant, but has a heavy performance cost. When the CPU chases a pointer to an object allocated somewhere in the heap, the prefetcher has no idea what memory address is coming next. It stalls, sitting idle for hundreds of cycles, waiting for main RAM to deliver the data.

We thrash the cache and waste the physical capabilities of our hardware. And when most of our entities don't emit audio, most of that work is for nothing.

The Pointer-Chasing Approach

If we instead try to adapt this object-oriented mindset to our SoA EntityStorage, we typically handle optional data through pointers. If an entity has audio, the pointer will point to an audio component. If not, the pointer is null:

1#pragma once
2#include <vector>
3#include <string>
4#include <memory> // for std::unique_ptr 
5
6struct AudioComponent {
7  float volume;
8  float pitch;
9  float pan;
10};
11
12class EntityStorage {
13public:
14  std::vector<std::string> m_names;
15  std::vector<std::unique_ptr<AudioComponent>> m_audio; 
16
17  int Add(std::string name) {
18    m_names.push_back(std::move(name));
19
20    // No audio by default, but can be added using function below
21    m_audio.push_back(nullptr); 
22
23    return int(m_names.size() - 1);
24  }
25
26  void AddAudioToEntity(int index) {
27    m_audio[index] = std::make_unique<AudioComponent>(); 
28  }
29};

This is simple. It saves RAM because we don't store a load of data we don't need for the 90% of entities that don't have audio. The pointer-chasing may be costly, but we'll benchmark it shortly.

The Data-Oriented Approach

Instead of pointers, what if we strictly optimize our memory footprint? We can create a separate container dedicated to exactly one type of optional data.

Let's implement our proximity functionality using a data-oriented design, using the familiar SoA layout. We'll call our container ProximityStorage:

1#pragma once
2#include <vector>
3#include <string>
4
5class ProximityStorage {
6public:
7  std::vector<float> m_distance;
8  std::vector<float> m_angle;
9  std::vector<float> m_occlusion;
10
11  int Add(float distance, float angle, float occlusion) {
12    m_distance.push_back(distance);
13    m_angle.push_back(angle);
14    m_occlusion.push_back(occlusion);
15    return int(m_distance.size() - 1);
16  }
17};

If we have ten thousand entities in our world, but only a thousand of them are close enough to need proximity data, those thousand records sit packed shoulder-to-shoulder. If an entity doesn't need it, it simply doesn't exist in the pool.

There currently isn't anything linking an entity in EntityStorage to its proximity data in ProximityStorage. We'll do that in the next lesson, but for now, we're just interested in comparing the performance of these approaches.

Let's set up three benchmarks that test our approaches across a range of collection sizes $n$. We're estimating that around 10% of our entities will have each of these optional components, so our benchmarks are as follows:

• BM_VirtualDispatch: A traditional object-oriented approach. A vector of $n$ GameObject pointers, where roughly 10% are instantiated as an AudioObject subclass that overrides a virtual method.
• BM_PointerChasing: An EntityStorage containing $n$ records, where roughly 10% allocate a pointer to an AudioComponent.
• BM_ContiguousSoA: A flat, data-oriented ProximityStorage containing only the $n / 10$ records that actually exist.

Each approach will process the same amount of meaningful data, and our system will perform the same basic accumulation work on each underlying layout:

1#include <benchmark/benchmark.h>
2#include <random>
3#include <memory>
4#include <dsa/EntityStorage.h>
5#include <dsa/ProximityStorage.h>
6
7// OOP Hierarchy for benchmarking
8struct GameObject {
9  virtual ~GameObject() = default;
10  virtual float GetVolume() const { return 0.0f; }
11};
12
13struct AudioObject : public GameObject {
14  float volume = 1.0f;
15  float pitch = 1.0f;
16  float pan = 0.0f;
17  float GetVolume() const override { return volume; }
18};
19
20static void BM_VirtualDispatch(benchmark::State& state) {
21  int n = state.range(0);
22  std::vector<std::unique_ptr<GameObject>> entities;
23  entities.reserve(n);
24
25  std::mt19937 rng(42);
26  std::uniform_int_distribution<int> dist(0, 9);
27  for (int i = 0; i < n; ++i) {
28    if (dist(rng) == 0) {
29      entities.push_back(std::make_unique<AudioObject>());
30    } else {
31      entities.push_back(std::make_unique<GameObject>());
32    }
33  }
34
35  for (auto _ : state) {
36    float total_volume = 0.0f;
37    for (const auto& entity : entities) {
38      total_volume += entity->GetVolume();
39    }
40    benchmark::DoNotOptimize(total_volume);
41  }
42}
43
44static void BM_PointerChasing(benchmark::State& state) {
45  int n = state.range(0);
46  EntityStorage es;
47
48  std::mt19937 rng(42);
49  std::uniform_int_distribution<int> dist(0, 9);
50  for (int i = 0; i < n; ++i) {
51    es.Add("Player");
52    if (dist(rng) == 0) {
53      es.AddAudioToEntity(i);
54    }
55  }
56
57  for (auto _ : state) {
58    float total_volume = 0.0f;
59    for (const auto& audio_ptr : es.m_audio) {
60      if (audio_ptr) {
61        total_volume += audio_ptr->volume;
62      }
63    }
64    benchmark::DoNotOptimize(total_volume);
65  }
66}
67
68static void BM_ContiguousSoA(benchmark::State& state) {
69  int n = state.range(0) / 10;
70  ProximityStorage ps;
71
72  for (int i = 0; i < n; ++i) {
73    ps.Add(1.0f, 0.0f, 0.0f);
74  }
75
76  for (auto _ : state) {
77    float total_distance = 0.0f;
78    for (float dist : ps.m_distance) {
79      total_distance += dist;
80    }
81    benchmark::DoNotOptimize(total_distance);
82  }
83}
84
85#define BENCHMARK_CONFIG(name) \
86  BENCHMARK(name) \
87    ->RangeMultiplier(10) \
88    ->Range(100'000, 10'000'000) \
89    ->Unit(benchmark::kMillisecond)
90
91BENCHMARK_CONFIG(BM_VirtualDispatch);
92BENCHMARK_CONFIG(BM_PointerChasing);
93BENCHMARK_CONFIG(BM_ContiguousSoA);

1--------------------------------------
2Benchmark                          CPU
3--------------------------------------
4BM_VirtualDispatch/100000     0.185 ms
5BM_VirtualDispatch/1000000     2.05 ms
6BM_VirtualDispatch/10000000    25.4 ms
7BM_PointerChasing/100000      0.112 ms
8BM_PointerChasing/1000000      1.19 ms
9BM_PointerChasing/10000000     18.6 ms
10BM_ContiguousSoA/100000       0.007 ms
11BM_ContiguousSoA/1000000      0.071 ms
12BM_ContiguousSoA/10000000     0.837 ms

The traditional object-oriented and pointer-based approaches fail on three fronts:

1. Excessive Iteration: We're forced to iterate through the entire collection of entities, evaluating and discarding 90% of them.
2. Branch Misprediction & Indirect Calls: Whether evaluating a null check using if (audio_ptr) or looking up a function address in a virtual table using entity->GetVolume(), the CPU cannot reliably predict the outcome. These effectively random checks lead to frequent pipeline flushes.
3. Cache Misses: When an entity does have the optional data, we must chase a pointer to a random memory address in the heap. The prefetcher can't anticipate this, resulting in massive stalls due to memory latency.

The data-oriented ContiguousSoA approach wins because it only processes data that exists, and it does so in a straight line with zero pointer indirection or virtual dispatch overhead.

We have just demonstrated the mechanical foundation of the Entity-Component-System (ECS) architecture.

Instead of relying just on inheritance, ECS relies on composition. There are many variations of this pattern, but a typical implementation looks something like this:

• Entities are simple, lightweight objects that uniquely identify an entity in our world. This is generally done using a basic integer, or a handle that includes a generational index .
• Components are the data associated with an entity. If an entity has the ability to play audio, that means that there is an audio component that is linked to that entity in some way. That audio component might contain variables like what audio file is currently being played and its volume.
• Systems implement functionality. For example, our audio system might iterate over all the audio components and analyze their variables to determine what the player should currently hear.

Our application loop would then update (or "tick") all of our systems on every iteration:

1int main() {
2  // ...
3  while (isRunning) {
4    PhysicsSystem.Update();
5    AudioSystem.Update();
6    // ...
7  }
8  // ...
9}

If all of our systems can access and process the data they need quickly enough, the incremental, ticking nature of our program is effectively invisible. When iterations of this loop happen every few milliseconds, the program feels like it is running and responding to user input immediately, in "real time".

When we add a system to our program, it needs access to the data in our components. We do not store an entity's components together in memory. Instead, components live in dedicated component pools. A component pool is simply a container, exactly like our ProximityStorage, dedicated to exactly one type of component.

By storing our data in this manner, our audio or proximity systems can process all of their required components with the full efficiency of working with contiguous, SoA data:

However, our approach currently has an obvious gap: it has no concept of ownership. We have a pool of entities in EntityStorage, and a pool of components in ProximityStorage. An entity can't "own" a component because there is nothing linking components and entities together.

We'll set up that connective tissue in the next lesson, using sparse sets.