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:

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

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:

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

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:

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

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:

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

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:

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:

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

Note that this TransformComponent is using the Vec2 type we created earlier in the course to represent two-dimensional vectors. A fully 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:

1// Entity.h
2// ...
3#include "TransformComponent.h"
4
5class Entity {
6public:
7  // ...
8  TransformComponent* AddTransformComponent() {
9    // Add a new TransformComponent, emplace_back()
10    // constructs it in place and returns a
11    // reference to the added element
12    ComponentPtr& NewComponent{
13      Components.emplace_back(
14        std::make_unique<
15          TransformComponent>())};
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};

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

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

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. AddTransformComponent() 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 to solve a problem unless we're sure it is a problem. 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:

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

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:

1// Entity.h
2// ...
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};

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:

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

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

Dynamic Arrays using `std::vector`

Explore the fundamentals of dynamic arrays with an introduction to std::vector

View Related Lesson

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:

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

We cover lambdas in our advanced course:

Lambdas

An introduction to lambda expressions - a concise way of defining simple, ad-hoc functions

View Related Lesson

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:

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

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.

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

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:

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

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:

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

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:

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

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 course:

Standard Library Views

Learn how to create and use views in C++ using examples from std::views

View Related Lesson

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:

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

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 future Owner, and 1, 2, and 3 are additional arguments for that type's constructor:

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

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

A better design that combines flexibility whilst allowing the Entity to manage the full lifecycle of its components might look something like this:

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

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

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

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

Function templates 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 concepts. 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 variadic function 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 perfect forwarding. 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.

Function Templates

Understand the fundamentals of C++ function templates and harness generics for more modular, adaptable code.

View Related Lesson

Concepts in C++20

Learn how to use C++20 concepts to constrain template parameters, improve error messages, and enhance code readability.

View Related Lesson

Variadic Functions

An introduction to variadic functions, which allow us to pass a variable quantity of arguments

View Related Lesson

Perfect Forwarding and `std::forward`

An introduction to problems that can arise when our functions forward their parameters to other functions, and how we can solve those problems with std::forward

View Related Lesson

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

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

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

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};

Complete Code

Our complete code, which we'll build upon throughout this chapter, is available below:

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 crucial for 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

The `Entity` Class

The `Scene` Class

The Game Loop

Creating Components

Retrieving Components

Removing Components

Dynamic Arrays using `std::vector`

Multiple Components of the Same Type

Advanced: Alternative Designs

Using `std::move()`

Using Templates

Function Templates

Concepts in C++20

Variadic Functions

Perfect Forwarding and `std::forward`

Complete Code

Summary

Entity and Component Interaction

Game Development with SDL2

Implementing a Component System

Base Classes

The Component Class

The Entity Class

The Scene Class

The Game Loop

Creating Components

Retrieving Components

Removing Components

Dynamic Arrays using std::vector

Multiple Components of the Same Type

Advanced: Alternative Designs

Using std::move()

Using Templates

Function Templates

Concepts in C++20

Variadic Functions

Perfect Forwarding and std::forward

Complete Code

Summary

Entity and Component Interaction

The `Component` Class

The `Entity` Class

The `Scene` Class

Dynamic Arrays using `std::vector`

Using `std::move()`

Perfect Forwarding and `std::forward`