Gaia-ECS is a fast, ergonomic C++17 ECS framework designed to be the option you can actually learn in an afternoon without reading a manual the size of a novel. You get complex queries with relationship traversal, per-component AoS/SoA layouts, integrated serialization, and multithreading with job dependencies — all behind an API that stays out of your way.

Highlights:

• Clean, safe API — no boilerplate, no footguns
• Hybrid storage model — archetype/chunk storage for fast iteration, sparse storage for low-cost frequent modification
• Expressive queries: relationships, wildcards, hierarchy traversal (DFS/BFS), variables
• Per-component AoS or SoA data layout with minimal code changes
• Integrated compile-time and runtime serialization
• Multithreading with job dependencies, including parallel ECS iteration
• No external dependencies, no STL strings or containers
• Single-header option — drop it in and go
• Compiles fast, runs on all major compilers, even in web browser thanks to Emscripten

Quality:

• Thoroughly documented — both public API and internals
• Correctness ensured by thousands of unit tests, in-code asserts, and sanitizers

NOTE: Due to its extensive use of acceleration structures and caching, this library is not a good fit for hardware with very limited memory resources (measured in MiBs or less). Micro-controllers, retro gaming consoles, and similar platforms should consider alternative solutions.

Table of Contents

• Introduction
  • ECS
  • Implementation
  • Project structure
• Usage
  • Minimum requirements
  • Basic operations
    • Create or delete entity
    • Add or remove component
    • Component presence
    • Component scope
    • Non-fragmenting and sparse components
    • Name entity
    • Component hooks
    • Bulk editing
    • Set or get component value
    • Copy entity
    • Entity cleanup
    • Batched creation
    • Entity lifespan
    • Archetype lifespan
  • Data processing
    • Query
    • Simple query
    • Query traversal
    • Traversal order
    • Query variables

Introduction

ECS

Entity-Component-System (ECS) is an architectural pattern that organizes code around data rather than objects, following the principle of composition over inheritance.

Instead of modeling your program around real-world objects (car, house, human), you think in terms of the data needed to achieve a result. When moving something from A to B you don't care if it's a car or a plane — you only care about its position and velocity. This makes code easier to maintain, extend, and reason about, while also being more naturally suited to how modern hardware works.

Think of ECS as a database engine without ACID constraints — optimized for latency and throughput beyond what a general-purpose database could achieve, at the cost of data safety guarantees. Queries over entities are fast by design, and data locality is a first-class concern rather than an afterthought.

The three building blocks are:

• Entity — a unique id that represents an object in your world
• Component — a piece of data attached to an entity (position, velocity, health)
• System — logic that operates on all entities matching a given set of components

A vehicle is any entity with Position and Velocity. Add Driving and it's a car. Add Flying and it's a plane. The movement systems only care about the components they need — nothing else.

Implementation

Gaia-ECS is a hybrid ECS combining archetype-based storage with sparse storage. Unique combinations of components are grouped into archetypes — think of them as database tables where components are columns and entities are rows.

Each archetype is made up of chunks: fixed-size allocation blocks selected per archetype from a small set of size classes. Compact archetypes use small cache-friendly chunks, while wider dense archetypes can use larger chunks to reduce per-chunk iteration overhead. Components of the same type are laid out linearly within a chunk, minimizing heap allocations and keeping iteration cache-friendly.

The main strengths of this layout are fast iteration, predictable memory usage, and natural parallelism. The tradeoff is that adding or removing fragmenting ids requires moving data between archetypes — mitigated here by an archetype graph and support for batched component changes.

Gaia-ECS also supports selected component data living outside chunk columns when a different tradeoff is needed. That keeps the main archetype path optimized for dense iteration while still allowing more dynamic, optional, or less cache-sensitive data to use a different storage path.

Queries are compiled into bytecode and executed by an internal virtual machine, ensuring only the complexity your query actually needs is paid for.

Components are themselves entities with a Component tag attached. Treating components as first-class entities is what enables relationships and keeps the overall design orthogonal — the same mechanisms that handle entities handle components, without special cases.

Project structure

The entire project is implemented inside gaia namespace. It is further split into multiple sub-projects each with a separate namespaces.

• core - core functionality, use by all other parts of the code
• mem - memory-related operations, memory allocators
• cnt - data containers
• meta - reflection framework
• ser - serialization framework
• mt - multithreading framework
• ecs - the ECS part of the project

The project has a dedicated external section that contains 3rd-party code. At present, it only includes a modified version of the robin-hood hash-map.

Usage

Minimum requirements

#include <gaia.h>

The entire framework is placed in a namespace called gaia. The ECS part of the library is found under gaia::ecs namespace. In the code examples below we will assume we are inside gaia namespace.

Basic operations

Create or delete entity

Entity a unique "thing" in ecs::World. Creating an entity at runtime is as easy as calling World::add. Deleting is done via World::del. Once deleted, entity is no longer valid and if used with some APIs it is going to trigger a debug-mode assert. Verifying that an entity is valid can be done by calling World::valid.

ecs::World w;
// Create a new entity
ecs::Entity e = w.add();
// Check if "e" is valid. Returns true.
bool isValid = w.valid(e); // true
// Delete the entity
w.del(e);
// Check if "e" is still valid. Return false.
isValid = w.valid(e); // false

It is also possible to attach entities to entities. This effectively means you are able to create your own components/tags at runtime.

ecs::Entity player0 = w.add();
ecs::Entity player1 = w.add();
ecs::Entity player2 = w.add();
ecs::Entity teamA = w.add();
ecs::Entity teamB = w.add();
// Add player0 and player1 to teamA
w.add(player0, teamA);
w.add(player1, teamA);
// Add player2 to teamB
w.add(player2, teamB);

Name entity

Each e