Templatizing Components

In the previous lessons, we proved that splitting our data into relational component pools and joining them with Bitmasks is efficient for the hardware. It keeps our memory contiguous and our caches hot.

However, the code required to use these systems is currently a disaster. The rest of the course will be focused on taking these efficient algorithms and hiding them behind a friendly interface that makes our ECS easy and safe for others to use.

To add a component to an entity, we currently have to manually add the data to the specific storage class, manually calculate which bit corresponds to that component, and manually update the entity's signature:

1int alice = entities.Add("Alice");
2proximity.Add(alice, 1.0f, 2.0f, 3.0f);
3entities.RegisterComponent(alice, 1 << 0);
4audio.Add(alice, 4.0f, 5.0f, 6.0f);
5entities.RegisterComponent(alice, 1 << 1);

Aside from being annoying to use, it is also prone to errors. If we change the order of our bits, or if we forget to register a component after adding data, our system breaks.

In this lesson, we are going to use templates to automate this wiring. We will build a registry that manages our storage systems, and an entity handle that allows us to write expressive code like this:

1world.CreateEntity("Alice")
2  .AddComponent<Proximity>(1.0f, 2.0f, 3.0f)
3  .AddComponent<Audio>(4.0f, 5.0f, 6.0f);

In the next lesson, we'll allow our component pools to be queried using an API that looks like this:

1// Get all the entities that have both a proximity
2// and audio component
3auto noisy_neighbors = world.GetView<Proximity, Audio>();
4
5for (auto [entity, prox, audio] : noisy_neighbors) {
6  std::print(
7    "Processing audio for {} (distance = {}, volume = {})",
8    entity.name, prox.distance, audio.volume
9  );
10}

We will achieve this with zero overhead. The compiler will do all the heavy lifting at compile time, leaving us with the same machine code as the manual versions.

Recommended Reading: Class Templates , Function Templates , Template Specialization

Currently, our EntityStorage, ProximityStorage, and AudioStorage are just loose variables floating around in main(). There is no single object that "owns" the game state.

We need a central hub. In most ECS implementations, this is called the registry or the world.

Component Type Traits

The immediate problem with implementing a component-centric API like AddComponent<Audio> is that the idea of a "component" is entirely conceptual. There is no type called AudioComponent or Audio. We have AudioStorage, but that has a different meaning - that is, a pool of components, not an individual component.

Consumers shouldn't care how our components are stored, and we don't want our API to be AddComponent<AudioStorage>. So, let's create a utility that we can use behind the scenes to map friendly component categories like Audio to their underlying storage, like AudioStorage.

We'll need this mapping in a few places, so we'll create a standalone type trait. We don't actually need an Audio type for any reason other than to support this API. It has no data, and we'll never instantiate it, so it can just be a tag - an empty struct that is used only to convey information at compile time:

1#pragma once
2#include "AudioStorage.h"
3#include "ProximityStorage.h"
4
5// Base implementation just echos back the same type,
6// but we can add specializations later
7template <typename T>
8struct StorageFor {
9  // StorageFor<T>::Type returns T
10  using Type = T;
11};
12
13// Specializations
14struct Audio {}; // Tag
15template <>
16struct StorageFor<Audio> {
17  // StorageFor<Audio>::Type returns AudioStorage
18  using Type = AudioStorage;
19};
20
21struct Proximity {}; // Tag
22template <>
23struct StorageFor<Proximity> {
24  // StorageFor<Proximity>::Type returns ProximityStorage
25  using Type = ProximityStorage;
26};

We'll see how this is practically useful in the next section, but here is an example of how a hypothetical AddComponent() function template might use this to understand what type of pool it needs to interact with:

1#include <dsa/Registry.h>
2
3template <typename ComponentType>
4void AddComponent() {
5  using PoolType = typename StorageFor<ComponentType>::Type;
6  // ...
7}
8
9int main() {
10  // PoolType within AddComponent will be AudioStorage
11  AddComponent<Audio>();
12
13  // PoolType within AddComponent will be ProximityStorage
14  AddComponent<Proximity>();
15}

Tracking Component Pools

Recommended Reading: Tuples

To help the registry keep track of all our component pools, we will make heavy use std::tuple.

A std::tuple is a fixed-size collection. Unlike a std::ector, the size of the collection is known at compile time. This allows the compiler to calculate the memory offset of every storage system during the build process, eliminating the need for runtime lookups.

Another important property of std::tuple that it is heterogeneous - each entry can have a different type. Each of our component pools has a different type (AudioStorage, ProximityStorage, etc) so we'll need this.

Let's define our Registry class. It will hold our main EntityStorage and a tuple containing our component storages.

1#pragma once
2#include <tuple>
3#include "EntityStorage.h"
4#include "AudioStorage.h"
5#include "ProximityStorage.h"
6
7template <typename T>
8struct StorageFor {
9  using Type = T;
10};
11
12struct Audio {};
13template <>
14struct StorageFor<Audio> {
15  using Type = AudioStorage;
16};
17
18struct Proximity {};
19template <>
20struct StorageFor<Proximity> {
21  using Type = ProximityStorage;
22};
23
24class Registry {
25public:
26  EntityStorage entities;
27
28  std::tuple<
29    ProximityStorage,
30    AudioStorage
31  > components;
32};

Accessing Storage by Type

Now that our storages are wrapped in a tuple, we can no longer access them by name. We have to access them by type or index using std::get(). That would look something like the following:

1#include <tuple> // for std::get
2#include "Registry.h"
3
4int main() {
5  Registry World;
6  AudioStorage& pool = std::get<AudioStorage>(World.components);
7}

This isn't too bad, but our ideal API might look more like this:

1#include "Registry.h"
2
3int main() {
4  AudioStorage& pool = World.GetStorage<Audio>();
5}

We already have our StorageFor type trait that maps components like Audio to the corresponding AudioStorage type.

Let's use this within a new GetStorage<T>() that implements the std::get() logic behind the scenes. Note that StorageFor() returns the type of the component pool, whilst GetStorage() returns the pool itself - the actual object that our world is using to store the components:

1// ...
2
3class Registry {
4public:
5  // ...
6
7  template <typename T>
8  auto& GetStorage() {
9    using StorageType = typename StorageFor<T>::Type;
10    return std::get<StorageType>(components);
11  }
12};

This might look like a search operation, but it isn't. The std::get() access resolves at compile time. If we ask for Audio, the compiler knows exactly where that object lives inside the tuple (e.g., "Offset 0"). The resulting assembly instruction is a direct memory access.

Example Usage

With these changes, our code can now grab a reference to each pool that is in use:

1#include <dsa/EntityStorage.h>
2#include <dsa/ProximityStorage.h>
3#include <dsa/AudioStorage.h>
4#include <dsa/Registry.h>
5
6int main() {
7  EntityStorage entities;
8  ProximityStorage proximity;
9  AudioStorage audio;
10  Registry GameWorld;
11  
12  // Adding entities
13  int alice = GameWorld.entities.Add("Alice");
14  
15  // Adding Components
16  GameWorld.GetStorage<Proximity>().Add(alice, 1.0f, 2.0f, 3.0f);
17}

This has made creating our world much easier, but has made interacting with it even more complex. Let's fix that next.

Now that we have a World, we need a friendly way to interact with the entities inside it.

When we called entities.Add() in previous lessons, it returned an int (the index). It doesn't know about the World it belongs to, and it doesn't have any methods to add components.

We will wrap this integer in a lightweight EntityHandle struct. Previously, this idea of a handle is what let us implement generational indexing.

We could do that again here, but in this section, we're focusing on adding friendly functions to our handle that simplify interactions with our registry.

1#pragma once
2#include "Registry.h"
3
4struct EntityHandle {
5  Registry* world;
6  int id;
7
8  // We will add methods here soon...
9};

We need to update our Registry class to return this handle when we create an entity:

Recommended Reading: Variadic Functions , Fold Expressions , Perfect Forwarding

We want to add a method to EntityHandle that allows us to add a component to the entity. The syntax we want is:

1handle.AddComponent<Audio>(1.0f, 2.0f, 3.0f);

The arguments (1.0f, 2.0f, 3.0f) need to be passed from our handle to the AudioStorage::Add() function.

If we were writing this for just one type, it would look like this:

1void AddAudio(float v, float p, float pan) {
2  world->GetStorage<Audio>().Add(id, v, p, pan);
3}

But we want this to work for any storage system, which might take any number of arguments. Some arguments might be large objects, and we do not want to copy them unnecessarily as we pass them through our handle.

To solve this, we use variadic templates and perfect forwarding.

1. Variadic Templates (typename... Args): This tells the compiler "This function accepts any number of arguments of any type."
2. Forwarding References (Args&&...): This allows the function to accept both temporary objects - like 3.0f or std::string("Hello") - and existing variables.
3. Perfect Forwarding using std::forward: This casts the arguments back to their original value category (l-value or r-value) when passing them to the final destination.

This ensures that if we pass a temporary object, it gets moved all the way to the destination storage. If we pass a variable by reference, it stays a reference.

1#pragma once
2#include "Registry.h" 
3
4struct EntityHandle {
5  Registry* world;
6  int id;
7
8  template <typename ComponentType, typename... Args>
9  EntityHandle& AddComponent(Args&&... args) {
10    // Get the storage system, eg Audio -> AudioStorage
11    auto& storage = world->GetStorage<ComponentType>();
12
13    // Call .Add() on that storage
14    // We pass our ID, followed by the forwarded arguments
15    storage.Add(id, std::forward<Args>(args)...);
16
17    // Return *this to allow chaining
18    // eg .AddComponent<A>(...).AddComponent<B>(...)
19    return *this;
20  }
21};

This is a zero-overhead abstraction. At compile time, the AddComponent() function effectively vanishes. The compiler sees AddComponent() calls GetStorage() (which is just an offset) and then calls Add(). It inlines the whole chain. The resulting assembly is indistinguishable from calling audio.Add(id, ...) directly.

Example Usage

Finally, we have our goal API:

1#include <dsa/Registry.h>
2
3int main() {
4  Registry GameWorld;
5  
6  // Before:
7  int alice = GameWorld.entities.Add("Alice");
8  GameWorld.GetStorage<Proximity>().Add(alice, 1.0f, 2.0f, 3.0f);
9  GameWorld.GetStorage<Audio>().Add(alice, 4.0f, 5.0f, 6.0f);
10  
11  // After:
12  GameWorld.CreateEntity("Alice")
13    .AddComponent<Proximity>(1.0f, 2.0f, 3.0f)
14    .AddComponent<Audio>(4.0f, 5.0f, 6.0f);
15  
16  // If we want to save a handle for future interactions:
17  EntityHandle Bob = GameWorld.CreateEntity("Bob");
18  
19  // ...
20  
21  Bob.AddComponent<Audio>(7.0f, 8.0f, 9.0f);
22}

One thing remains - we need to update our entity's signature when a key component is added.

Previously, we required that to be done manually. A system needed to Add() a component to the corresponding pool, and then notify the EntityStorage that a key component was added through a RegisterComponent() function:

1// Update AudioStorage
2audio.Add(alice, 4.0f, 5.0f, 6.0f);
3// Update EntityStorage
4entities.RegisterComponent(alice, 1 << 1);

We now have a registry to manage these cross-storage updates. We can have AddComponent() update both EntityStorage and the corresponding component pool, like AudioStorage, automatically.

As a reminder, to update a bit, we provide the entity ID and the component's bit to EntityStorage::RegisterComponent():

1// ...
2
3class EntityStorage {
4public:
5  // ...
6  void RegisterComponent(int entity_id, uint8_t bit) {
7    if (entity_id < m_signatures.size()) {
8      m_signatures[entity_id] |= bit;
9    }
10  }
11};

But how do we know which bit corresponds to AudioStorage?

1#pragma once
2#include "World.h"
3
4struct EntityHandle {
5  World* world;
6  int id;
7
8  template <typename ComponentType, typename... Args>
9  EntityHandle& AddComponent(Args&&... args) {
10    auto& storage = world->GetStorage<ComponentType>();
11    storage.Add(id, std::forward<Args>(args)...);
12    
13    world->entities.RegisterComponent(id, /* ?? */);
14    
15    return *this;
16  }
17};

There are two approaches we can use for this. We can specify which bit corresponds to each component, or we can automatically assign bits to component types based on their position in our std::tuple.

Option 1: Custom Signatures

Individually assigning pools to bits gives us the ability to exclude component types from the signature. Remember, these signatures are a performance optimization to allow systems to more quickly determine if a player has a specific key component.

If we add all of our components to this signature, the signature gets physically larger, reducing cache efficiency. If a component isn't in the signature, we can still find out if an entity has it by traversing the component pool's sparse array.

Again, we can use a trait to define these mappings at compile time. By default, a component has no bit (-1). We only specialize the trait for the "hot" components that need to be part of the signature optimization.

In this example, we'll assume Proximity is a key component, but Audio is less frequently queried, so will be excluded from the signature:

1// ...
2
3// Default: Component is not in the signature
4template <typename T>
5struct BitmaskFor {
6  static constexpr int value = -1;
7};
8
9// Proximity is Bit 0
10template <>
11struct BitmaskFor<Proximity> {
12  static constexpr int value = 0;
13};
14
15class Registry {
16  // ...
17};

We can then update our EntityHandle to check this trait at compile time using if constexpr. If the value is valid (not -1), we update the signature in the EntityStorage:

1// ...
2
3struct EntityHandle {
4  Registry* world;
5  int id;
6
7  template <typename ComponentType, typename... Args>
8  EntityHandle& AddComponent(Args&&... args) {
9    auto& storage = world->GetStorage<ComponentType>();
10    storage.Add(id, std::forward<Args>(args)...);
11
12    // Update signature (if applicable)
13    constexpr int bit = BitmaskFor<ComponentType>::value;
14    if constexpr (bit != -1) {
15      world->entities.RegisterComponent(id, 1 << bit);
16    }
17
18    return *this;
19  }
20};

Option 2: Automated Signatures

For many projects, we just want every component to have a bit. Since our registry already defines the order of our components in its std::tuple, we can simply use that order to assign our bits.

• Index 0 in the tuple, maps to bit 0 in the signature
• Index 1 in the tuple, maps to bit 1 in the signature, and so on

We want to implement this using an API that can be used like:

1int bit = Registry::GetBitIndex<Proximity>();

So, we'd map Proximity to ProximityStorage using our previous type trait, and we then find the index of ProximityStorage within the std::tuple that stores all of our component pools.

Unfortunately, std::tuple still has no built-in way to tell us where a given type lives.

The usual solution involves a recursively-defined type trait, shown below. Don't worry if it looks baffling - most people don't write this code - we just ritualistically copy and paste it into any project where std::tuple is involved:

1// ...
2
3// Helper to find the index of T in a Tuple
4template <typename T, typename Tuple>
5struct TupleIndex;
6
7// Base Case: Found it at the start
8template <typename T, typename... Types>
9struct TupleIndex<T, std::tuple<T, Types...>> {
10  static constexpr int value = 0;
11};
12
13// Recursive Case: It's not the first one, look in the rest
14template <typename T, typename U, typename... Types>
15struct TupleIndex<T, std::tuple<U, Types...>> {
16  static constexpr int value = 1 + TupleIndex<
17    T, std::tuple<Types...>
18  >::value;
19};
20
21// ...

We can now use this to implement our GetBitIndex() function template. We'll also alias our complex std::tuple type name with a using statement, so we can easily refer to it in multiple places:

1// ...
2
3class Registry {
4public:
5  // ...
6  using ComponentTuple = std::tuple<
7    ProximityStorage,
8    AudioStorage
9  >;
10  
11  ComponentTuple components;
12
13  template <typename T>
14  static constexpr int GetBitIndex() {
15    // Get the storage type (e.g. Audio -> AudioStorage)
16    using StorageType = typename StorageFor<T>::Type;
17    
18    // Find the index of AudioStorage in the tuple (1)
19    return TupleIndex<StorageType, ComponentTuple>::value;
20  }
21  // ...
22};

And now, finally, our EntityHandle can ask the Registry what bit corresponds to the component it is trying to add:

1// ...
2
3struct EntityHandle {
4  // ...
5  template <typename ComponentType, typename... Args>
6  EntityHandle& AddComponent(Args&&... args) {
7    auto& storage = world->GetStorage<ComponentType>();
8    storage.Add(id, std::forward<Args>(args)...);
9
10    // Automatically calculate the bit
11    constexpr int bit = Registry::GetBitIndex<ComponentType>();
12    world->entities.RegisterComponent(id, 1 << bit);
13
14    return *this;
15  }
16};

We'll stick with option 2 in this example, as it makes our future work slightly easier. We'll explain why that is in the next lesson.

A complete version of the example we created in this lesson is provided below:

We have transformed a brittle, manual system into a friendly, error-proof API. Here are the key points:

1. The Registry: We grouped our unrelated storage systems into a single compile-time list managed by a std::tuple. This gives us type-safe access without runtime overhead.
2. Entity Handles: We created a lightweight object to facilitate interaction with our system in an intuitive, entity-centric way.
3. Perfect Forwarding: We used typename... Args and std::forward to pass arguments through our handle directly to the underlying storage, ensuring no unnecessary copies are made.
4. Automated Signatures: We used the tuple index to automatically assign unique bitmasks to each component.

We have solved the "insertion" problem - adding data is now clean and easy.

But we still have the "query" problem. Our ProximityAudioSystem from the previous lesson required a monstrous 50-line function just to join data from two of our component pools.

Joining data is a pretty common requirement across systems, so we'll standardize it. In the next lesson, we'll let systems grab what they need using a view-based API like this:

1auto noisy_neighbors = world.GetView<Proximity, Audio>();
2for (auto [entity, prox, audio] : noisy_neighbors) {
3  // ...
4}