# Ecs Pattern > Expert Entity Component System (ECS) architecture for high-performance game engines — data-oriented design, archetype storage, system scheduling, cache-coherent iteration, and production tuning. - Skill: `j4flmao/ecs-pattern` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add j4flmao/ecs-pattern` - Raw SKILL.md: https://api.skillmd.com/api/skills/j4flmao/ecs-pattern/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: j4flmao (https://skillmd.com/u/j4flmao) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/j4flmao/ecs-pattern --- # Entity Component System (ECS) — Deep Engineering Guide ECS is the dominant data-oriented architecture for modern game engines (Unity DOTS, Bevy, Unreal Mass, Frostbite, Overwatch's ECS, Minecraft, Soldank, EnTT). It replaces scattered OOP objects with contiguous arrays of plain data so tens of thousands of entities update at 60 FPS on cache-limited CPUs. ## 1. Why ECS Exists: The Performance Rationale ### 1.1 The OOP Cache Problem A classic OOP hierarchy: ```cpp class GameObject { public: virtual void Update() = 0; glm::vec3 m_Position; float m_Health; std::vector m_Children; }; class Enemy : public GameObject { public: void Update() override; private: std::string m_Name; float m_Speed; }; ``` Each `Enemy` is heap-allocated individually. The pointer-chasing heap layout scatters `m_Position` across DRAM. Iterating 10,000 enemies forces the CPU to evict its L1/L2/L3 caches on **every single object**. The CPU does nothing but wait on memory. Measured impact: random-access iteration over a fragmented heap is **20–100x slower** than streaming over contiguous arrays. At 1.8 GHz × 8 cores, this is the difference between updating 1,000 and 100,000 entities per frame. ### 1.2 The Data-Oriented Answer ``` OOP layout (heap): [Enemy0][Enemy1][Enemy2] --- scattered pages --- Data layout (SoA): Position[].x = {2.1, 9.4, 5.0, ...} Position[].y = {0.0, 3.3, 8.2, ...} Health[] = {100, 42, 7, ...} ``` ### 1.3 The Three Pillars | Term | Definition | Example | |------|-----------|---------| | **Entity** | A lightweight opaque ID (integer). No data, no behavior. | `Entity(42)` is just `uint32_t 42` | | **Component** | A plain-data struct (POD, no virtuals, no methods beyond trivial accessors) | `struct Position { float x, y, z; }` | | **System** | Pure logic that reads/writes components for every matched entity | `MovementSystem` does `pos += vel * dt` | ### 1.4 Why This is Faster — Cache Lines A cache line is 64 bytes. A `Position + Velocity` pair in SoA form is 24 bytes. A cache-line fetch delivers **two entities' worth of hot data** instead of two pointers to cold data. This is called a **cache-miss-free stream**. ```mermaid %%{init: {"theme": "default", "flowchart": {"useMaxWidth": true}}}%% flowchart TD subgraph RAM ["DRAM: Component Arrays (SoA)"] A["Position[0..N] (contiguous)"] B["Velocity[0..N] (contiguous)"] C["Health[0..N] (contiguous)"] end subgraph CORE ["CPU L1/L2 Cache"] D["Cache Line: 64B"] E["prefetch next line"] end F["Movement System"] -->|"iterates pos[i]+=vel[i]"| A F --> B F -->|"next element already in cache"| D D --> E ``` ## 2. Storage Models ### 2.1 Naïve: Dictionary-of-Component-Arrays (AoS-friendly) The simplest ECS stores each component type in one flat array, where array index == entity ID: ```cpp struct PositionArray { std::vector data; }; // data[entity] = position struct HealthArray { std::vector data; }; // data[entity] = health ``` - **Pros**: minimal implementation, easy to reason about. - **Cons**: index collisions when entities are destroyed (holes), stale IDs trigger undefined behavior, and unused components occupy memory slots. ### 2.2 Sparse Set The canonical solution to sparse entity IDs. Two parallel arrays: ```cpp template class SparseSet { std::vector dense; // component payload, packed by insertion order std::vector sparse; // entity -> index into dense std::vector entities; // dense -> entity public: void add(Entity e, T comp) { sparse[e.id] = dense.size(); dense.push_back(comp); entities.push_back(e); } void remove(Entity e) { int idx = sparse[e.id]; dense[idx] = dense.back(); dense.pop_back(); entities[idx] = entities.back(); entities.pop_back(); sparse[entities[idx].id] = idx; } T& get(Entity e) { return dense[sparse[e.id]]; } }; ``` `sparse` maps entity → index; `dense` packs only *live* components. Destruction swaps the last element into the hole (O(1)) — exactly how EnTT, Bevy, and flecs remove entities. ### 2.3 Archetype / Chunk-Based Storage (Unity DOTS, Bevy, Unreal Mass) Archetypes group entities with **identical component shape**: ``` Archetype A = {Position, Velocity} archetype_id = hash([Position, Velocity]) Archetype B = {Position, Velocity, Health} ``` Each archetype owns contiguous "chunk" blocks (typically 4KB–16KB) that are pure SoA: ``` Chunk (16 KB): Position[0..maxEntity Per Chunk] Velocity[0..maxEntities] Health [0..maxEntities] -- only if archetype has Health ``` Entity ID → archetype ID → chunk index → row. When an entity gains/removes a component, it is **moved** to a different archetype (data migration). This yields: - Truly cache-coherent iteration (only the components the system needs). - Cheap add/remove via chunks (no per-entity allocation). - Zero pointer chasing. ### 2.4 EnTT's Hybrid Approach EnTT (the most popular single-header ECS) uses a **grouped sparse set** storage: - Components stored in sorted, tightly packed arrays. - Grouped storage keeps all components for an archetype in predictable order, collapsing cache misses. - `view<>` iteration yields pointer-like iterators for direct SoA traversal. ## 3. Entity Hierarchy ## 3.1 Entity IDs in Practice | Engine | Entity representation | |--------|----------------------| | Unity DOTS | `uint32_t` index + `uint32_t` version (generation counter) | | Bevy | `Entity { index: u32, generation: u32 }` | | EnTT | `entt::entity` = `uint32_t` (32-bit) or `uint64_t` with version bits | | flecs | `ecs_entity_t` = `uint64_t` with flags | | Unreal Mass | `FMassEntityHandle { uint32 SerialNumber; uint32 Index; }` | Generation counters prevent a recycled ID from silently colliding with a stale reference: ```cpp uint32_t index = id & 0xFFFF; // low 16 bits = index uint32_t generation = (id >> 16); // high 16 bits = version Entity create(uint32_t& nextIndex, std::vector& generation) { uint32_t idx = freeList; // reuse a freed slot uint32_t gen = generation[idx]; // bump the version generation[idx] = gen + 1; freeList = ...; // consume next freed slot return pack(idx, gen); } bool isValid(Entity e, const std::vector& generation) { return generation[e.index()] == e.generation(); // stale ID detected } ``` ## 4. Systems & Scheduling ## 4.1 System Signature A system declares the components it reads (`Reads`) and writes (`Writes`). The scheduler uses this to: 1. **Detect data races**: two systems writing the same component simultaneously are illegal. 2. **Parallelize**: systems with disjoint read/write sets run in parallel threads. 3. **Order deterministically**: a write/read dependency imposes an order edge. ```rust // Bevy style fn movement_system(time: Res