Let's put the composition pattern into practice by constructing a foundational Entity-Component System (ECS).

We will establish the necessary base classes (Entity, Component), use smart pointers (std::unique_ptr) for memory management, and implement the mechanisms for adding components to entities, querying entities for specific components, and removing components when they're no longer needed.

Base Classes

Let's start with our base classes. These will all follow a pattern we're familiar with by now, using our typical set of HandleEvent(), Tick(), and Render() functions.

The `Component` Class

Our base Component class looks like the following. Because we'll be using runtime polymorphism, we'll set our three functions to be virtual. We'll also add a virtual destructor to reduce the possibility of polymorphism-related memory leaks:

src/Component.h

1#pragma once
2#include <SDL3/SDL.h>
3
4class Component {
5public:
6  virtual void HandleEvent(const SDL_Event& E) {}
7  virtual void Tick(float DeltaTime) {}
8  virtual void Render(SDL_Surface* Surface) {}
9  virtual ~Component() = default;
10};

The `Entity` Class

Next, let's create the Entity class to manage these components. To support polymorphism, entities will store their components as an array of pointers.

We also want to automate memory management as much as possible, so we'll establish an ownership model where Entity objects "own" their components. As such, we'll store them as unique pointers:

src/Entity.h

1#pragma once
2#include <memory>
3#include <vector>
4#include <SDL3/SDL.h>
5#include "Component.h"
6
7using ComponentPtr = std::unique_ptr<Component>;
8using ComponentPtrs = std::vector<ComponentPtr>;
9
10class Entity {
11  ComponentPtrs Components;
12};

Our Entity objects will hook up to our game loop using the usual three functions, and it will forward all these calls to each of its components. We'll also mark these as virtual to allow entities to be polymorphic, too:

src/Entity.h

1#pragma once
2#include <memory>
3#include <vector>
4#include <SDL3/SDL.h>
5#include "Component.h"
6
7using ComponentPtr = std::unique_ptr<Component>;
8using ComponentPtrs = std::vector<ComponentPtr>;
9
10class Entity {
11 public:
12  virtual void HandleEvent(const SDL_Event& E) {
13    for (ComponentPtr& C : Components) {
14      C->HandleEvent(E);
15    }
16  }
17
18  virtual void Tick(float DeltaTime) {
19    for (ComponentPtr& C : Components) {
20      C->Tick(DeltaTime);
21    }
22  }
23
24  virtual void Render(SDL_Surface* Surface) {
25    for (ComponentPtr& C : Components) {
26      C->Render(Surface);
27    }
28  }
29
30  virtual ~Entity() = default;
31
32private:
33  ComponentPtrs Components;
34};

The `Scene` Class

Moving one level up the chain, our Scene class will look very similar, except it manages entities instead of components. We won't need the virtual functions here as we'll only have a single scene in our project:

src/Scene.h

1#pragma once
2#include <SDL3/SDL.h>
3#include <vector>
4#include "Entity.h"
5
6using EntityPtr = std::unique_ptr<Entity>;
7using EntityPtrs = std::vector<EntityPtr>;
8
9class Scene {
10public:
11  void HandleEvent(const SDL_Event& E) {
12    for (EntityPtr& Entity : Entities) {
13      Entity->HandleEvent(E);
14    }
15  }
16
17  void Tick(float DeltaTime) {
18    for (EntityPtr& Entity : Entities) {
19      Entity->Tick(DeltaTime);
20    }
21  }
22
23  void Render(SDL_Surface* Surface) {
24    for (EntityPtr& Entity : Entities) {
25      Entity->Render(Surface);
26    }
27  }
28
29private:
30  EntityPtrs Entities;
31};

The Game Loop

Finally, we'll hook everything up to a game loop and render it in an SDL_Window. The main.cpp and Window.h files are provided below, and they have not changed from what we have been using in previous sections:

Files

src

Select a file to view its content

Creating Components

Most game objects need a position, rotation, or scale - something to define where they are or how they're oriented. Let's create a TransformComponent for that:

src/TransformComponent.h

1#pragma once
2#include <iostream>
3#include "Vec2.h"
4#include "Component.h"
5
6class TransformComponent : public Component {
7public:
8  TransformComponent() {
9    std::cout << "TransformComponent created\n";
10  }
11
12  void Tick(float DeltaTime) override {
13    std::cout << "TransformComponent ticking\n";
14  }
15
16  Vec2 GetPosition() const {
17    return Position;
18  }
19
20private:
21  Vec2 Position{0, 0};
22};

Note that this TransformComponent is using the Vec2 type we created earlier in the course to represent two-dimensional vectors. A full copy of this type is available below:

Let's update our Entity to give them the ability to create a TransformComponent for themselves. This time, however, we won't just construct the component within our Entity.

Remember, our goal here is to allow each Entity object to only have the capabilities it needs. An Entity that is designed to play background music, for example, may not need to have a position, so does not need a TransformComponent.

So instead of having every Entity construct a TransformComponent for itself, we'll let whatever code is constructing our actor decide if it needs one. We'll provide them with a AddTransformComponent() function to call if it does.

In general, when a function adds a component to our actor, we'll also return a pointer to that component, so the calling code can interact with it:

src/Entity.h

1// ...
2#include "TransformComponent.h"
3
4class Entity {
5public:
6  // ...
7  TransformComponent* AddTransformComponent() {
8    // Add a new TransformComponent, emplace_back()
9    // constructs it in place and returns a
10    // reference to the added element
11    ComponentPtr& NewComponent{
12      Components.emplace_back(
13        std::make_unique<TransformComponent>()
14      )
15    };
16
17    // Convert the ComponentPtr ie 
18    // std::unique_ptr<Component> to the
19    // the return type: a TransformComponent* 
20    return static_cast<TransformComponent*>(
21      NewComponent.get()
22    );
23  }
24  // ...
25};

Let's update our Scene to add an Entity, and then add a component to that Entity:

src/Scene.h

1// ...
2
3class Scene {
4public:
5  Scene() {
6    EntityPtr& NewEntity{Entities.emplace_back(
7      std::make_unique<Entity>()
8    )};
9    NewEntity->AddTransformComponent();
10  }
11  // ...
12};

1TransformComponent created
2TransformComponent ticking
3TransformComponent ticking
4TransformComponent ticking
5...

Advanced

Data Locality

In larger projects, extra development effort would be spent to control exactly where our entities and components are stored in memory.

For objects that are typically processed together, ideally those objects would be stored physically close to each other in memory. The main benefit of data locality is that it allows CPU caching to be more effective, thereby increasing performance.

For example, we might introduce some system that ensures all of the TransformComponent instances across our whole scene are stored in a contiguous block of memory, perhaps managed by a std::vector. The AddTransformComponent() function would then interact with that system, rather than its current approach of letting std::make_unique() decide where to store the component.

However, we also shouldn't add complexity unless we're sure we'll need it. Our approach will be fine for simple scenes that don't have thousands of components, so we'll stick with it for now.

You can read more about data locality on Wikipedia, and Chapter 17 of Game Programming Patterns talks about its application in the context of a component system.

Retrieving Components

Often, external code or other components attached to the same Entity will need to access the data or functionality provided by a specific component. For example, a rendering component will need to know the entity's position, which is stored in its TransformComponent.

To facilitate this, we need a way to retrieve a specific component from an Entity. Since our Components vector stores base Component pointers, we'll iterate through the vector and use dynamic_cast to check if a component is of the requested type (TransformComponent, in this case).

The dynamic_cast operator safely converts pointers within an inheritance hierarchy at runtime. If the cast is successful, it returns a valid pointer to the derived type; otherwise, it returns nullptr. Our function will return the pointer to the found component, or nullptr if the Entity doesn't have one of that type:

src/Entity.h

1// ...
2
3class Entity {
4public:
5  // ...
6  TransformComponent* GetTransformComponent() const {
7    for (const ComponentPtr& C : Components) {
8      // Try to cast the base Component pointer
9      // to a TransformComponent pointer
10      if (auto Ptr{dynamic_cast<
11        TransformComponent*>(C.get())}) {
12        // Cast successful, we found it!
13        return Ptr;
14      }
15    }
16
17    // Went through all components, didn't
18    // find a transform component
19    return nullptr;
20  }
21  // ...
22};

Our Entity objects should have, at most, a single TransformComponent, so let's update our AddTransformComponent() function to enforce this with the help of this new GetTransformComponent() function:

src/Entity.h

1// ...
2#include <iostream>
3
4class Entity {
5public:
6  TransformComponent* AddTransformComponent() {
7    if (GetTransformComponent()) {
8      std::cout << "Error: Cannot have "
9        "multiple transform components";
10      return nullptr;
11    }
12
13    ComponentPtr& NewComponent{
14      Components.emplace_back(
15        std::make_unique<TransformComponent>()
16      )
17    };
18
19    return static_cast<TransformComponent*>(
20      NewComponent.get()
21    );
22  }
23  // ...
24};

Removing Components

Just as we need to add components to entities, we also need the ability to remove them. This might happen when an effect wears off, a weapon is dropped, or an entity changes state.

We'll add a RemoveComponent() function to our Entity class. It will take a raw pointer (Component*) to the component instance that needs to be removed.

This function then finds the std::unique_ptr managing the component associated with the raw pointer and removes it from the Components vector. There are a few ways to erase items from a std::vector. The approach that is likely to be most familiar is:

Determine the index of the value we want to erase
Create an iterator to that index by adding it to the value returned by the begin() method
Pass that iterator to the erase() method.

It looks like this:

src/Entity.h

1// ...
2
3class Entity {
4public:
5  // ...
6  void RemoveComponent(Component* PtrToRemove) {
7    // Iterate through the vector to find
8    // the component to remove
9    for (size_t i{0}; i < Components.size(); ++i) {
10      // Check if the raw pointer managed by
11      // the unique_ptr matches
12      if (Components[i].get() == PtrToRemove) {
13        // Found it! Erase the element at this index.
14        // Components.begin() + i gives an iterator
15        // to the element.
16        Components.erase(Components.begin() + i);
17        // Assuming only one component matches,
18        // so we can stop searching
19        return;
20      }
21    }
22    // If the loop finishes, the component
23    // wasn't found
24    std::cout << "Warning: Attempted to remove "
25      "a component not found on this entity.\n";
26  }
27  // ...
28};

We covered std::vector() and the erase() method in more detail in our

Advanced: Lambdas and `std::erase_if()`

A slightly more elegent (but also more advanced) way of conditionally erasing elements from an a array is through std::erase_if(), introduced in C++20.

The std::erase_if() function receives the array as the first argument, and a function as the second. The function we provide will be called for every element in the array, receiving that element as an argument. It should return true if that element should be erased, or false if it should be kept.

Rewriting our previous example using std::erase_if() and a lambda would look like this:

src/Entity.h

1// ...
2
3class Entity {
4public:
5  // ..
6  void RemoveComponent(Component* PtrToRemove) {
7    std::erase_if(Components,
8      [PtrToRemove](const ComponentPtr& P) {
9        return P.get() == PtrToRemove;
10      }
11    );
12  }
13  // ...
14};

We cover lambdas in our .

Multiple Components of the Same Type

One of the powerful advantages of composition over inheritance is the ability for an entity to possess multiple components of the same type. With inheritance, an object is a specific type (e.g., a Player is a Character). With composition, an entity has components.

There's no inherent restriction preventing an entity from having, for instance, two separate ImageComponent instances if we wanted it to render two different images simultaneously (perhaps one for the body and one for a held item).

We'll build a complete ImageComponent later in the chapter, but let's create a basic scaffolding now:

src/ImageComponent.h

1#pragma once
2#include <iostream>
3#include "Component.h"
4
5class ImageComponent : public Component {
6 public:
7  ImageComponent() {
8    std::cout << "ImageComponent created\n";
9  }
10};

To add these ImageComponent instances to our entities, we'll need an AddImageComponent() function in our Entity class, similar to the AddTransformComponent() we created earlier.

It will construct a new ImageComponent, add its unique_ptr to the Components vector, and return a raw pointer to the newly created component.

src/Entity.h

1// ...
2#include "ImageComponent.h" 
3
4class Entity {
5public:
6  // ...
7  ImageComponent* AddImageComponent() {
8    ComponentPtr& NewComponent{
9      Components.emplace_back(
10        std::make_unique<ImageComponent>()
11      )
12    };
13
14    return static_cast<ImageComponent*>(
15      NewComponent.get()
16    );
17  }
18  // ...
19};

Note: Our AddTransformComponent() and AddImageComponent() have a lot of very similar logic. We'll endure this duplication for now, but will discuss better designs in the next section.

Since an entity can have multiple ImageComponent instances, a function like GetTransformComponent() (which returns only one) isn't sufficient. We need a way to retrieve all ImageComponent instances associated with an entity.

Let's add a GetImageComponents() function. This function will iterate through the Components vector, perform a dynamic_cast() for each one, and collect all successful ImageComponent pointers into a std::vector. It then returns this vector, giving the caller access to all relevant components:

src/Entity.h

1// ...
2
3class Entity {
4public:
5  // ...
6
7  using ImageComponents = std::vector<ImageComponent*>;
8  ImageComponents GetImageComponents() const {
9    ImageComponents Result;
10    for (const ComponentPtr& C : Components) {
11      // Try to cast to ImageComponent*
12      if (auto Ptr{dynamic_cast<
13        ImageComponent*>(C.get())}
14      ) {
15        // If successful, add it to our
16        // result vector
17        Result.push_back(Ptr);
18      }
19    }
20    return Result;
21  }
22
23  // ...
24};

Advanced: Views

The GetImageComponents() function above works, but it has a minor inefficiency: it creates and returns a brand new std::vector every time it's called. This involves memory allocation and copying pointers. For performance-critical code or frequent calls, this could be undesirable.

C++20 introduced Ranges and Views, which provide a more modern and often more efficient way to work with sequences of data. A view is a lightweight object that represents a sequence of elements (often by referring to an existing container) but doesn't own the elements itself.

Views allow us to compose algorithms (like filtering and transforming) lazily, meaning the work is only done when the elements are actually accessed, and often without intermediate allocations.

We can rewrite GetImageComponents() to return a view instead of a vector. This view would represent the sequence of ImageComponent pointers without needing to create a separate container:

src/Entity.h

1// ...
2#include <ranges> // Required for views
3
4class Entity {
5public:
6  // ...
7  auto GetImageComponents() {
8    // Define the transformation:
9    //   ComponentPtr -> ImageComponent*
10    auto ToImagePtr{[](const ComponentPtr& C) {
11      return dynamic_cast<ImageComponent*>(C.get());
12    }};
13
14    // Define the filter:
15    //    Keep only non-nullptr pointers
16    auto IsNotNull{[](ImageComponent* Ptr){
17      return Ptr != nullptr;
18    }};
19
20    // Create the view:
21    // 1. View the Components vector.
22    // 2. Transform each element using ToImagePtr.
23    // 3. Filter the results using IsNotNull.
24    return Components
25      | std::views::transform(ToImagePtr)
26      | std::views::filter(IsNotNull);
27  }
28  // ...
29};

Views support most of the same capabilities as their underlying container. For example, we can use the view to count how many ImageComponents an Entity has, and to iterate over them:

src/Scene.h

1// ...
2
3class Scene {
4 public:
5  Scene() {
6    EntityPtr& NewEntity{Entities.emplace_back(
7      std::make_unique<Entity>()
8    )};
9    NewEntity->AddImageComponent();
10    NewEntity->AddImageComponent();
11    NewEntity->AddImageComponent();
12
13    std::cout << "Image Component Count: "
14      << std::ranges::distance(
15           NewEntity->GetImageComponents());
16
17    for (ImageComponent* C :
18         NewEntity->GetImageComponents()) {
19      std::cout << "\nDoing something with"
20                   " an ImageComponent...";
21      // ...
22    }
23  }
24};

1ImageComponent created
2ImageComponent created
3ImageComponent created
4Image Component Count: 3
5Doing something with an ImageComponent...
6Doing something with an ImageComponent...
7Doing something with an ImageComponent...

We cover views in much more detail in our

Advanced: Alternative Designs

This section reimplements our previous functionality using more advanced C++ techniques. We'll continue to use the simple approach created above for the rest of the course, so feel free to skip this section if preferred.

This approach where we define methods like AddTransformComponent() and AddImageComponent() on our Entity base class has a bit of a design problem in more complex programs:

Every time we add a new component type, such as a PhysicsComponent, we need to add a new AddPhysicsComponent() method to our Entity class.
Every time we add a new constructor to a component type, or update an existing constructor's parameter list, we need to add or update a method on the Entity class to support the constructor's parameter list.
We'd soon find ourselves with dozens of similar methods in our Entity class and, if we need to change something about how components get added in general, we'd probably need to update all of those methods.

We'll cover two alternative designs in this section. The first option solves the problem but creates a different issue, and the second option solves the problem but requires more advanced C++ techniques than what we've covered so far.

Using `std::move()`

An immediate solution to this problem would be to have the code outside of our Entity object be responsible for creating the components, and then std::move() them into the entity:

src/Entity.h

1// ...
2
3class Entity {
4  // ...
5  Component* AddComponent(ComponentPtr& NewComponent) {
6    Components.push_back(std::move(NewComponent));
7    return NewComponent.get();
8  }
9  // ...
10}

Using this function to add a component to an entity might look something like below, where ComponentType is a Component subclass, Player.get() is the component's Owner, and 1, 2, and 3 are additional arguments for that type's constructor:

src/Scene.h

1// ...
2
3class Scene {
4public:
5  Scene() {
6    EntityPtr& Player{Entities.emplace_back(
7      std::make_unique<Entity>()
8    )};
9
10    // Create the component
11    std::unique_ptr NewComponent{
12      std::make_unique<ComponentType>(
13        Player.get(), 1, 2, 3
14      )
15    };
16
17    // Move it to the Entity
18    Component* Ptr{Player->AddComponent(
19      std::move(NewComponent)
20    )};
21
22    // Cast the return value to the derived type
23    // if needed
24    ComponentType* Casted{
25      static_cast<ComponentType*>(Ptr)
26    };
27    Casted->SomeDerivedFunction();
28  // ...
29};

This is more flexible, but also has design problems. The obvious problem shown above is that the AddComponent() function is difficult to use - adding a component to an entity requires an unreasonable amount of code and complexity.

In a larger program, our AddComponent() function might be used in hundreds of locations. We really want the complexity to be in the one place where AddComponent() is defined (the Entity class) rather than the hundred places where it is used.

We'd also prefer that our Entity class manage the full lifecycle of its components to keep memory management simple and reduce the liklihood of memory-related bugs.

Using Templates

Our ideal design would include all 3 benefits:

the flexibility of allowing any component type with any argument list to be constructed without needing code updates
the Entity should manage the full lifecycle of its components
the API should be easy to use

That API might look something like this:

src/Scene.h

1// ...
2
3class Scene {
4public:
5  Scene() {
6    EntityPtr& Player{Entities.emplace_back(
7      std::make_unique<Entity>()
8    )};
9
10    ComponentType* NewComponent{
11      Player->AddComponent<ComponentType>(1, 2, 3)
12    };
13  }
14  // ...
15};

However, implementing this API within the Entity class involves using much more complex C++ features than we've covered so far:

src/Scene.h

1// ...
2
3class Entity {
4public:
5  // ...
6
7  ImageComponent* AddImageComponent() {}
23
24  template <typename CType, typename... CArgs>
25  requires std::derived_from<CType, Component>
26  CType* AddComponent(CArgs&&... ConstructorArgs) {
27    // Construct the component in our vector
28    ComponentPtr& NewComponent{
29      Components.emplace_back(
30        std::make_unique<CType>(
31          // Pass constructor args here
32          std::forward<CArgs>(ConstructorArgs)...
33        )
34      )
35    };
36
37    // Return component in the appropriate type
38    return static_cast<CType*>(
39      NewComponent.get());
40  }
41
42  // ...
43};

We cover these techniques in full detail in the advanced course, but to summarise the key points as they're applied here:

allow us to define function behaviours without necessarily knowing all the types we will be dealing with. In this example, we don't know the exact type of component we're adding. So, we create a template parameter called ComponentType to represent that type. External code then provides that parameter as an argument using < and > syntax when they use our template: AddComponent<SomeType>()
The requires syntax is an example of a C++20 feature called . In this case, we're using it to ensure the ComponentType template argument that the external code supplied is either the Component type, or a type that derives from Component.
The ... syntax is used to define a function or template with an unknown number of parameters, sometimes called a (or variadic template). This is primarily used for functions and templates that collect arguments to forward to some other function or template. In this case, our AddComponent() function is collecting arguments to forward to a constructor on the ComponentType class.
The double-ampersand && next to the Args type, and the use of the std::forward() function template, relates to a technique called . This ensures each argument get forwarded from one function to the next without performance loss through unnecessary copying, and without losing characteristics such as const.

Replacing our GetTransformComponent() with a template GetComponent() function would look like this:

src/Entity.h

1// ...
2
3class Entity {
4public:
5  // ...
6  TransformComponent* GetTransformComponent() {}
23
24  template <typename CType>
25  requires std::derived_from<CType, Component>
26  CType* GetComponent() {
27    for (const ComponentPtr& C : Components) {
28      // Try to cast the base Component pointer
29      // to a CType pointer
30      if (auto Ptr{dynamic_cast<CType*>(C.get())}) {
31        // Cast successful, we found it!
32        return Ptr;
33      }
34    }
35
36    // Went through all components, didn't
37    // find a CType component
38    return nullptr;
39  }
40
41  // ...
42};

And we can replace GetImageComponents() with a GetComponents() function in a similar way:

src/Entity.h

1// Entity.h
2// ...
3
4class Entity {
5public:
6  // ...
7
8  ImageComponents GetImageComponents() {}
24
25  template <typename CType>
26  requires std::derived_from<CType, Component>
27  std::vector<CType*> GetComponents() {
28    std::vector<CType*> Results;
29    for (const ComponentPtr& C : Components) {
30      // Try to cast to ImageComponent*
31      if (auto Ptr{dynamic_cast<CType*>(C.get())}) {
32        // If successful, add it to our result vector
33        Results.push_back(Ptr);
34      }
35    }
36    return Results;
37  }
38
39  // ...
40};

We'll stick with the basic approach of separate functions in future examples, but if you're following along and feel more comfortable, feel free to use one of the more advanced techniques.

Complete Code

Our complete code, which we'll build upon in the next lesson, is available below:

Files

src

Select a file to view its content

Summary

This lesson laid the groundwork for our Entity-Component System. We defined the Component and Entity base classes, making them polymorphic with virtual functions and destructors.

Entities now manage their components through a vector of unique pointers, ensuring proper ownership. We implemented key methods: AddComponent-style functions to attach capabilities, GetComponent-style functions (using dynamic_cast) to access them, and RemoveComponent() to detach them.

We also differentiated between components expected once per entity versus those allowed multiple times. Key takeaways:

Polymorphic base classes (Component, Entity) are the foundations of ECS.
std::unique_ptr within a std::vector provides robust component ownership for entities.
Adding components involves creating derived types and storing base pointers.
Retrieving specific components requires runtime type checking (dynamic_cast).
The system supports both single-instance (e.g., Transform) and multi-instance (e.g., Image) component types per entity.
Entities can dynamically gain and lose components via AddComponent() and RemoveComponent()style methods.

Implementing a Component System

Base Classes

The Component Class

src/Component.h

The Entity Class

src/Entity.h

src/Entity.h

The Scene Class

src/Scene.h

The Game Loop

Files

Creating Components

src/TransformComponent.h

src/Entity.h

src/Scene.h

Retrieving Components

src/Entity.h

src/Entity.h

Removing Components

src/Entity.h

Advanced: Lambdas and std::erase_if()

src/Entity.h

Multiple Components of the Same Type

src/ImageComponent.h

src/Entity.h

src/Entity.h

Advanced: Views

src/Entity.h

src/Scene.h

Advanced: Alternative Designs

Using std::move()

src/Entity.h

src/Scene.h

Using Templates

src/Scene.h

src/Scene.h

src/Entity.h

src/Entity.h

Complete Code

Files

Summary

Entity and Component Interaction

The `Component` Class

The `Entity` Class

The `Scene` Class

Advanced: Lambdas and `std::erase_if()`

Using `std::move()`