Skip to content

ECS Feature Docs

These documents zoom in on each feature of the ECS described in ../design.md. The design gives the big picture (requirements, choices, how the ECS sits on top of the engine layer); each feature doc explains one part on its own, so it can be understood, discussed and later implemented separately.

They are concept explainers: what the feature is, why we need it, how other ECSs do it, what we chose, how it works, and what can go wrong. Snippets are illustrative and omit the Epitech header and the rule-of-five members; the real code follows docs/CodeStyle.md.

The requirements are the ones from the design:

# Requirement
R1 Bevy-style engine: the ECS owns the loop, engine features are plugins.
R2 Luau-first games: components, systems, entities and plugins written in Luau.
R3 Multiplayer with an authoritative server: inputs up, state down.
R4 Generic and reusable beyond R-Type.

Reading order

# Doc In one line Version
01 Entity Generational ids and the allocator that recycles them v1
02 Component registry How every component (C++ or Luau) is described, named and laid out v1
03 Sparse array Paged map from entity index to a position in a pool v1
04 Pool Packed storage of one component: entities, bytes, ticks v1
05 Archetype tables Optional table storage for stable, hot components v3
06 World The container that owns everything; several per process v1
07 Queries Finding entities by components, typed and dynamic v1
08 Change detection Added/changed ticks and Mut<T> v1
09 Commands Deferred spawn, despawn, add, remove v1
10 Resources Singletons, including main-thread-only ones v1
11 Events Double-buffered messages between systems v1
12 Systems Logic, declared access, C++ functions and Luau classes v1
13 Scheduler Phases, ordering, fixed timestep, run conditions, States v1 / v2
14 App and plugins The main loop, plugins, standalone mode v1
15 Reflection and serialization Field lists and the one generic serializer v1 / v2
16 Hooks and observers Lifecycle callbacks: memory only, observers later v1 / v3
17 Hierarchy Parent/child entities and transform propagation v2
18 Capsules Entities described once and spawned by copy: actors and levels alike, in plugin-capsule v2
19 Luau bridge How scripts declare components, systems, plugins and inputs v2
20 Replication The network plugins for an R-Type-like game v2

How the features depend on each other

flowchart BT
    entity["01 Entity"]
    registry["02 Component registry"]
    sparse["03 Sparse array"]
    pool["04 Pool"]
    tables["05 Archetype tables"]
    world["06 World"]
    queries["07 Queries"]
    change["08 Change detection"]
    commands["09 Commands"]
    resources["10 Resources"]
    events["11 Events"]
    systems["12 Systems"]
    scheduler["13 Scheduler"]
    app["14 App and plugins"]
    reflection["15 Reflection"]
    hooks["16 Hooks"]
    hierarchy["17 Hierarchy"]
    actors["18 Capsules"]
    luau["19 Luau bridge"]
    replication["20 Replication"]

    sparse --> pool
    entity --> pool
    registry --> pool
    pool --> world
    tables --> world
    hooks --> pool
    world --> queries
    change --> queries
    world --> commands
    world --> resources
    world --> events
    queries --> systems
    commands --> systems
    resources --> systems
    events --> systems
    systems --> scheduler
    scheduler --> app
    registry --> reflection
    app --> hierarchy
    reflection --> actors
    app --> luau
    reflection --> luau
    actors --> luau
    app --> replication
    reflection --> replication
    change --> replication

An arrow means "is used by". The bottom of the graph (entity, registry, sparse array, pool) has no dependency on the rest and can be built and tested first.

Template

Every doc follows the same outline:

  1. What it is: the feature in plain words.
  2. Why we need it: the requirements it serves and the features that depend on it.
  3. How others do it: EnTT, flecs, Bevy, Unity DOTS, Unreal Mass, where relevant.
  4. Our choice: the decision and why.
  5. How it works: diagrams and a few snippets.
  6. Connections: links to the features it uses and is used by.
  7. Pitfalls: what goes wrong and how the design avoids it.
  8. Open questions: only the ones specific to the feature.