How to Implement a Basic Entity-Component System for 2D Games

Core Concepts: Entities, Components, and Systems Explained

In the world of game development and high-performance applications, the Entity-Component-System (ECS) architecture is a game-changer. It's a design pattern that decouples domain-specific behaviors from data, enabling scalable and efficient systems. Let's break down the core concepts.

#include <vector>
#include <iostream>

struct Position {
    float x, y;
};

struct Velocity {
    float dx, dy;
};

void updatePositionSystem(std::vector<Position>& Position, std::vector<Velocity>& Vel) {
    for (int i = 0; i < Position.size(); i++) {
        Position[i].x += Vel[i].dx;
        Position[i].y += Vel[i].dy;
    }
}
            

Designing Your First Component Types for 2D Games

Now that you understand the theoretical architecture of Entity Component Systems (ECS), it is time to get your hands dirty. In traditional Object-Oriented Programming, you might be tempted to create a Player class with methods like Move() and Draw(). In ECS, we strip behavior away entirely. Components are pure data. They are the nouns of your game world, while Systems are the verbs.

Designing effective components requires a shift in mindset. You are not designing objects; you are designing data structures that describe state. A component should never know about other components. It should not know it exists. It simply holds data that a System might query later.

Notice the separation in the diagram above. The Movement System reads Position and Velocity, but it doesn't care about Render data. This decoupling is the superpower of ECS. It allows you to add new features without breaking existing logic. For a deeper dive into why this approach beats traditional class hierarchies, read our guide on composition vs inheritance in oop.

// 1. Position Component: Pure state
struct Position {
    float x;
    float y;
};

// 2. Velocity Component: Pure state
struct Velocity {
    float dx;
    float dy;
};

// 3. Render Component: Pure state
struct Render {
    int spriteID;
    int zIndex;
};

// 4. Health Component: Pure state
struct Health {
    int current;
    int max;
};

These structs are lightweight. They are designed to be packed tightly in memory for cache efficiency. When you write your how to implement basic game loop in logic, you will iterate over arrays of these structs, not objects.

struct Player {
    void Move() { ... } // BAD
    void Attack() { ... } // BAD
};

struct Position {
    float x, y; // GOOD
};
// MovementSystem handles logic

When designing your how to create tile maps for 2d games, remember that the map itself is just a collection of Position and Render components for each tile. Do not over-engineer the component. If a component is only used by one system, consider if it should even be a component or just part of that system's internal state.

Building the Entity Manager: Storing and Managing Game Objects

Welcome to the engine room. If the Component is the data and the System is the logic, the Entity Manager is the conductor of the orchestra. It is the central authority responsible for the lifecycle of every object in your game world. Without a robust manager, your game becomes a "spaghetti code" nightmare of scattered pointers and memory leaks.

As a Senior Architect, I demand you treat the Entity Manager not just as a list, but as a high-performance memory allocator. We are moving away from the naive "List of Objects" approach towards a data-oriented design that respects CPU cache lines.

1. The Identity Crisis: Integers vs. UUIDs

The first architectural decision you face is: How do we identify an entity?

In a naive implementation, you might use a pointer or a UUID. However, in high-performance game development, we prefer 32-bit or 64-bit Integers. Why? Because integers are cheap to compare and index arrays with.

2. Memory Layout: The Cache Coherence Problem

This is where the rubber meets the road. When you iterate through 10,000 entities to update their physics, how are they stored in RAM?

If you use a standard Object-Oriented approach (Array of Structs), your CPU cache misses will skyrocket. We must use Struct of Arrays (SoA).

[ Entity 0 ]
[ Entity 1 ]
[ Entity 2 ]
                

Positions: [P0, P1, P2...]
Velocities: [V0, V1, V2...]
Healths: [H0, H1, H2...]
                

3. Implementation: The Manager Class

Let's look at a production-ready C++ implementation. Notice how we use a std::vector for the component storage and a std::map (or hash map) to link Entity IDs to their component indices.

#include <vector>
#include <unordered_map>
#include <memory>

// A simple component representing Position
struct PositionComponent {
    float x, y;
};

class EntityManager {
private:
    // The "Pool": A contiguous block of memory for components
    std::vector<PositionComponent> positionPool;
    
    // Mapping Entity ID to Index in the Pool
    // This allows O(1) access to data
    std::unordered_map<int, size_t> entityMap;

public:
    // Create a new entity and assign it a position
    int CreateEntity(float x, float y) {
        int newEntityId = entityMap.size(); // Simple ID generation
        
        // Add data to the contiguous pool
        positionPool.push_back({x, y});
        
        // Link the ID to the index in the vector
        entityMap[newEntityId] = positionPool.size() - 1;
        
        return newEntityId;
    }

    // Update position efficiently
    void UpdatePosition(int entityId, float newX, float newY) {
        // Check if entity exists
        if (entityMap.find(entityId) != entityMap.end()) {
            size_t index = entityMap[entityId];
            positionPool[index].x = newX;
            positionPool[index].y = newY;
        }
    }
    
    // Iterate over all entities (Cache Friendly!)
    void ProcessAllEntities() {
        // We iterate the vector directly, ignoring the map
        // This is the key to high performance
        for (auto& pos : positionPool) {
            // Logic here...
        }
    }
};

4. The Singleton Pattern Debate

Should the Entity Manager be a Singleton? While convenient, global state is often an anti-pattern in modern software architecture. Instead, pass the manager as a dependency to your Systems. This makes your code more testable and modular.

If you must use a Singleton, ensure it is thread-safe. For a deep dive into this pattern, refer to how to implement singleton pattern in C++.

If Entities are the nouns and Components are the adjectives, then Systems are the verbs. They are the engines of logic that drive your application forward. In a traditional Object-Oriented design, logic is scattered across classes. In ECS, logic is centralized in Systems that process data in bulk.

As a Senior Architect, I urge you to think of a System not as a class, but as a filter and a processor. It asks the World, "Give me everything that has a Position and a Velocity," and then it executes a tight loop to update them. This separation is the key to achieving the performance seen in modern game engines and high-frequency trading platforms.

The Power of Data-Oriented Design

The magic of ECS lies in how Systems access memory. By processing components in contiguous arrays (Struct of Arrays), we maximize CPU cache hits. When a System iterates over 10,000 entities, it isn't chasing pointers; it is streaming data linearly.

// The System Logic
void MovementSystem::update(float deltaTime) {
    // 1. Query: Get all entities with Position and Velocity
    auto entities = world.query<Position, Velocity>();

    // 2. Iterate: Process them in a tight loop
    for (auto entity : entities) {
        // 3. Access: Direct memory access (Cache Friendly!)
        auto& pos = entity.get<Position>();
        auto& vel = entity.get<Velocity>();

        // 4. Update: Apply logic
        pos.x += vel.x * deltaTime;
        pos.y += vel.y * deltaTime;
    }
}
        

This linear access pattern allows the CPU to predict memory fetches, resulting in performance that scales linearly, or $O(n)$, where $n$ is the number of active entities. For a deeper dive into memory management patterns, you might explore how to implement singleton pattern in C++ to understand how to manage the global state of your World.

The animation above demonstrates the "tick." In a real application, this loop runs 60 times per second. If you need to handle complex behaviors, you can decompose your logic into smaller systems, similar to the how to implement strategy pattern for algorithmic variations in OOP.

Implementing a Basic ECS Framework in Code

You have the theory. Now, let's look at the engine room. Implementing an Entity Component System (ECS) isn't about writing complex magic; it's about disciplined data management. As a Senior Architect, I want you to see ECS not as a library you import, but as a design pattern you construct.

We are moving away from the "God Class" anti-pattern. Instead of one massive object trying to do everything, we are building a data pipeline. This approach is the foundation of modern game engines and high-performance simulations.

The Core Implementation

Let's build a minimal viable ECS in JavaScript. Notice how Component is purely data (POJO), and System is purely logic. This separation is the heart of composition vs inheritance in oop.

// 1. The Component (Data Only)
class Position {
    constructor(x, y) {
        this.x = x;
        this.y = y;
    }
}

class Velocity {
    constructor(dx, dy) {
        this.dx = dx;
        this.dy = dy;
    }
}

// 2. The System (Logic Only)
class MovementSystem {
    constructor() {
        this.name = "MovementSystem";
    }

    update(entities) {
        // Query: Find all entities with BOTH Position and Velocity
        entities.forEach(entity => {
            if (entity.has(Position) && entity.has(Velocity)) {
                const pos = entity.get(Position);
                const vel = entity.get(Velocity);

                // Logic: Apply velocity to position
                pos.x += vel.dx;
                pos.y += vel.dy;
            }
        });
    }
}

// 3. The World (Manager)
class World {
    constructor() {
        this.entities = [];
        this.systems = [];
    }

    addSystem(system) {
        this.systems.push(system);
    }

    update() {
        // The Game Loop Heartbeat
        this.systems.forEach(system => system.update(this.entities));
    }
}

The Lifecycle of a Frame

How does data actually flow? When you press a key or a timer ticks, the Game Loop triggers. The Systems query the World for specific data signatures, process them, and move on.

Managing Component Storage: Arrays vs Sparse Sets

In high-performance systems, how you store data is just as critical as the data itself. As a Senior Architect, I often tell my team: "Cache locality is king." When building an Entity Component System (ECS), the choice between a simple Dense Array and a Sparse Set determines whether your game loop runs at 60 FPS or 10 FPS.

Let's dissect the memory layout and performance characteristics of these two strategies.

The Memory Layout Visualization

Visualizing the difference is crucial. In a Dense Array, the CPU can predict the next memory address. In a Sparse Set, we trade a bit of memory overhead (the "Sparse" array) for the ability to jump directly to the data we need.

Implementation Logic

Here is the core logic of a Sparse Set. Notice how we use the sparse array to find the index in the dense array. This allows us to iterate over the dense array (which is compact) while still having instant access via the entity ID.

// Pseudocode for a Sparse Set Component Storage
// This structure is vital when implementing how to implement basic game loop in high-performance engines.

struct SparseSet {
    int* dense;   // Stores active entities (compact)
    int* sparse;  // Maps Entity ID -> Index in dense
    int size;     // Number of active entities
    int capacity; // Max capacity

    // O(1) Check if entity exists
    bool has(int entityID) {
        if (entityID >= capacity) return false;
        int index = sparse[entityID];
        return (index < size && dense[index] == entityID);
    }

    // O(1) Add Entity
    void add(int entityID) {
        if (has(entityID)) return;
        
        dense[size] = entityID;
        sparse[entityID] = size;
        size++;
    }

    // O(1) Remove Entity (Swap-and-Pop)
    void remove(int entityID) {
        if (!has(entityID)) return;

        int index = sparse[entityID];
        int lastEntity = dense[size - 1];

        // Swap with last element
        dense[index] = lastEntity;
        sparse[lastEntity] = index;
        
        size--;
    }
};

Architect's Note: The "Swap-and-Pop" technique used in remove() is a classic algorithmic trick. It preserves $O(1)$ complexity but destroys the order of elements. If order matters, you must use a different strategy, similar to the logic found in how to implement lru cache for specific data structures.

Why This Matters for Performance

When your game loop iterates through thousands of entities, you want the CPU to fetch data in "cache lines" (chunks of memory).

• Dense Arrays are perfect for the "Update" phase of your loop because the CPU prefetches the next component automatically.
• Sparse Sets are perfect for the "Spawn/Despawn" phase where you need to quickly check if an entity exists without scanning the whole list.

Entity Lifecycle Management: Creation, Activation, and Destruction

In the architecture of high-performance systems, an Entity is more than just a data container; it is a transient resource with a finite lifespan. Just like memory management in C++, the lifecycle of an entity must be strictly controlled to prevent leaks, dangling pointers, and state corruption. We move beyond simple "spawning" to a rigorous state machine approach that ensures stability under load.

The Four Phases of Existence

Implementation: The Safe Entity Manager

Here is a robust C++ implementation of an Entity Manager. Notice the use of a std::vector for the active list and a separate std::vector for deferred deletions. This pattern is essential for maintaining cache locality while ensuring safety.

#include <vector>
#include <memory>
#include <algorithm>

class Entity {
public:
    int id;
    bool active;
    Entity(int i) : id(i), active(true) {}
};

class EntityManager {
private:
    std::vector<std::shared_ptr<Entity>> entities;
    std::vector<int> deferredDeletions;

public:
    // 1. Creation
    int CreateEntity() {
        int newId = entities.size();
        entities.push_back(std::make_shared<Entity>(newId));
        return newId;
    }

    // 2. Request Destruction (Safe)
    void DestroyEntity(int id) {
        // Mark for deferred deletion
        deferredDeletions.push_back(id);
    }

    // 3. Update Cycle (The "Tick")
    void Update() {
        // A. Process Active Entities
        for (auto& entity : entities) {
            if (entity->active) {
                // Logic here...
            }
        }

        // B. Cleanup Deferred Deletions
        for (int id : deferredDeletions) {
            // Find and remove from main vector
            entities.erase(
                std::remove_if(entities.begin(), entities.end(),
                [id](const std::shared_ptr<Entity>& e) {
                    return e->id == id;
                }),
                entities.end()
            );
        }
        deferredDeletions.clear();
    }
};

Architect's Note: If you are building a system where entities are created and destroyed every frame (like particle effects), consider using an Object Pool pattern to avoid the overhead of frequent memory allocation.

Advanced Patterns: Queries, Filters, and Grouping Entities

In high-performance architectures, iterating over every single entity to check if it belongs to a specific system is a recipe for disaster. As your simulation scales, naive loops become $O(n)$ bottlenecks. To solve this, we move from imperative iteration to declarative querying. This section explores how to build a robust Query System that filters entities based on component composition efficiently.

The core of this efficiency lies in how we represent entity data. Instead of deep inheritance trees, we rely on Composition. This aligns with the composition vs inheritance in oop principle, allowing us to mix and match behaviors dynamically without rigid class hierarchies.

// Component Type Identifiers
enum class ComponentType : uint32_t {
    Position = 1 << 0,
    Velocity = 1 << 1,
    Renderable = 1 << 2,
    Physics = 1 << 3
};

// Entity Signature
struct EntitySignature {
    uint32_t mask;
};

// Query Logic
bool MatchesQuery(EntitySignature entity, uint32_t requiredMask) {
    // Check if entity has ALL required bits set
    return (entity.mask & requiredMask) == requiredMask;
}

Common Pitfalls and How to Avoid Them in ECS Design

Entity Component System (ECS) is a powerful architectural pattern for game development and high-performance applications. However, even seasoned developers can fall into traps that compromise performance, maintainability, and scalability. Let's explore the most common pitfalls and how to avoid them.

1. Putting Logic in Components

Anti-pattern: Components should only hold data. When you embed logic in components, you break the ECS principle of separation of concerns.

// ❌ Logic inside component
public class HealthComponent {
    public int CurrentHealth;
    public int MaxHealth;

    // ❌ This is logic, not data!
    public void TakeDamage(int damage) {
        CurrentHealth -= damage;
        if (CurrentHealth <= 0) Die();
    }

    private void Die() {
        // Death logic here
    }
}
    

// ✅ Pure data component
public class HealthComponent {
    public int CurrentHealth;
    public int MaxHealth;
}

// ✅ Logic in system
public class HealthSystem : ISystem {
    public void Update(Entity[] entities) {
        foreach (var entity in entities) {
            if (entity.TryGetComponent<HealthComponent>(out var health)) {
                if (health.CurrentHealth <= 0) {
                    // Handle death logic here
                }
            }
        }
    }
}
    

2. Tight Coupling Between Systems

Systems should operate independently. When systems directly reference each other, you lose the benefits of modularity and testability.

// ❌ Direct system coupling
public class MovementSystem {
    private CollisionSystem collisionSystem;

    public void Update() {
        // ❌ Directly calling another system
        var collisions = collisionSystem.GetCollisions();
        foreach (var collision in collisions) {
            // Handle movement based on collision
        }
    }
}
    

// ✅ Event-driven decoupling
public class CollisionEvent {
    public Entity EntityA;
    public Entity EntityB;
}

public class MovementSystem {
    private EventBus eventBus;

    public void Update() {
        // ✅ Listen for events instead
        eventBus.Subscribe<CollisionEvent>(HandleCollision);
    }

    private void HandleCollision(CollisionEvent evt) {
        // Handle movement based on collision event
    }
}
    

3. Incorrect System Update Order

Systems must execute in a deterministic order. If input processing happens after physics simulation, you'll get inconsistent behavior.

4. Over-Engineering with Too Many Components

Creating too many granular components can lead to management overhead and performance issues. Each component adds indirection.

// ❌ Too many small components
public class PositionComponent { public float X, Y; }
public class VelocityComponent { public float VX, VY; }
public class AccelerationComponent { public float AX, AY; }
public class RotationComponent { public float Angle; }
public class ScaleComponent { public float ScaleX, ScaleY; }
    

// ✅ Consolidated transform component
public class TransformComponent {
    public float X, Y;           // Position
    public float VX, VY;         // Velocity
    public float AX, AY;         // Acceleration
    public float Angle;          // Rotation
    public float ScaleX, ScaleY; // Scale
}
    

5. Ignoring Cache-Friendliness

ECS thrives on data locality. If your components are scattered in memory or you're jumping between unrelated systems, you'll miss out on cache performance.