Skip to content

ECS in C++: Design, Debugging, and Trade-Offs

Learn to choose boundaries rather than automatically replace OOP with ECS. This course follows one C++ simulation through a real change, alternative implementations, identity, component processing, debugging, and maintenance.

Main Course: Ten Connected Chapters

  1. C++ Design Boundaries: Start with Requirements
  2. Plain C++ Structs and Loops: Build the Baseline
  3. Add Acceleration to a C++ Simulation Before Refactoring
  4. C++ Records vs Composition vs Inheritance: One Change
  5. C++ Entity Identity and Ownership Without ECS
  6. C++ ECS Components and Systems: Benefits and Costs
  7. C++ ECS Execution Order and Deferred Changes
  8. Debug C++ ECS State: Trace Writers and Execution Order
  9. Maintain C++ ECS: Invariants, Change Impact, and Tests
  10. Choose Records, Composition, or ECS for C++ Projects

Read in order on your first pass. Chapters 1–4 establish the problem and compare a change before introducing identity or ECS. Chapters 5–7 add mechanisms only for named requirements. Chapters 8–10 investigate faults, preserve invariants, and decide whether those mechanisms are worth keeping.

You can adopt the record or composition design without completing an ECS implementation. The final chapter is a decision, not a graduation to “faster code.”

One Simulation, One Observable Contract

Bodies have position, optional movement, visibility, and lifetime. Chapter 3 adds optional acceleration before movement. An invisible moving body still moves. An expiring body receives its final movement before removal.

The same fixtures drive records, composition, inheritance, owner-scoped IDs, and component stores. Snapshots are copied values. Tests compare complete normalised states and independently calculated trajectories.

Question Evidence
Where does a change belong? Actual acceleration edit maps
Can I understand one body's behaviour? Per-body update paths and system writer traces
What prevents incorrect state? Validation, owner checks, cleanup, and order tests
What will the team maintain? Stores, IDs, queues, failure policies, and tests

Correct output is not proof of maintainability. Edit maps and traces support judgement; no hardware speed claim is made.

Prerequisites and Builds

Know structs, functions, references, vectors, optional values, RAII, and basic polymorphism. For preparation, see Modern C++ and Design Patterns.

The project uses C++17, CMake, and the standard library. There is no engine, GPU, display, GPIO, external ECS dependency, or SSH prerequisite. Hardware benchmarking is postponed.

Follow chapter 2's download and build instructions. Tests work in Debug and Release and do not depend on assertions.

Optional Extensions

Only after the corresponding requirement appears:

Extension overview and build. Neither extension is required by the main course; even its deferred queue uses non-reused IDs.

Verification and Limits

The supplied project is tested locally with GNU C++ 15.2.0 in Debug and Release. This is not Raspberry Pi hardware testing. Numeric overflow under unbounded workloads, concurrency, serialization, generic queries, and runtime capability editing are outside the demonstrated contract.

Earlier article URLs redirect to their corresponding revised chapters. Source history preserves the previous course; it is not a second active learning path.

Start with requirements and boundaries.

Donate