gz-ecs-overview

# gz-sim ECS architecture in 5 minutes

```
                ┌──────────────────────────────────────────┐
                │                 Server                   │
                │  (one process, owns N runners)           │
                └──────┬───────────────────────────────────┘
                       │
            ┌──────────▼──────────────────────────┐
            │         SimulationRunner            │
            │  - drives the iteration loop        │
            │  - owns the EventManager            │
            │  - owns the EntityComponentManager  │
            │  - owns the System list             │
            └──────────┬──────────────────────────┘
                       │ every step
   ┌───────────────────┼───────────────────────────────────────┐
   ▼                   ▼                   ▼                   ▼
Configure*       PreUpdate*           Update*             PostUpdate*
(once on load)   (mutates ECM)        (mutates ECM)       (read-only)
                                      └── Reset hooks on /reset
```

## The core types

| Type | Header | Role |
|------|--------|------|
| `Entity` | `Entity.hh` | Just a `uint64_t` ID. Means nothing on its own. |
| `components::Component<T, id>` | `components/Component.hh` | Strongly-typed data attached to an Entity. |
| `EntityComponentManager` | `EntityComponentManager.hh` | The world's database. Add/remove/query components. |
| `EventManager` | `EventManager.hh` | Pub/sub for cross-system events. |
| `System` (`ISystemConfigure`, `ISystemPreUpdate`, `ISystemUpdate`, `ISystemPostUpdate`, `ISystemReset`) | `System.hh` | Behaviour. Plugins implement one or more of these. |
| `SimulationRunner` | (internal) | Owns and drives the above. |
| `Server` | `Server.hh` | Public façade — `Run()`, `SetUpdatePeriod()`, etc. |

## Adding behaviour: pick a system phase

* **`Configure()`** — once on plugin load. Read SDF, cache handles, register
  topics. Do *not* mutate the world here unless you're spawning fixtures.
* **`PreUpdate()`** — every iteration, *before* physics. Apply commands
  (forces, joint targets), spawn entities.
* **`Update()`** — every iteration, alongside physics. Most user code does
  *not* belong here.
* **`PostUpdate()`** — every iteration, *after* physics. **Read-only ECM**
  access — emit telemetry, publish state, write logs. The ECM is `const`
  here for a reason.
* **`Reset()`** — when the world resets (e.g. via `/world/<name>/control`).
  Restore any internal state cached in the system.

## The "Cmd / state / Reset" component triplet

A common pattern in gz-sim:

* `<X>` — current value (e.g. `JointPosition`).
* `<X>Cmd` — request from a user system, consumed and cleared in
  `PreUpdate` by the physics-coupled system.
* `<X>Reset` — value to apply at the next world reset.

Look at `components/JointPositionReset.hh` / `JointVelocityCmd.hh` for the
canonical examples.

## Querying the ECM efficiently

Prefer `Each<>` views — they're cached and re-used across iterations:

```cpp
_ecm.Each<components::Joint, components::JointVelocity>(
  [&](const Entity &_ent,
      const components::Joint *,
      const components::JointVelocity *_vel) -> bool
  {
    // do work with *_vel
    return true; // keep iterating
  });
```

`EachNew`, `EachRemoved`, `EachChanged` exist for change-detection passes.

## Where things live

* **Component definitions** — `include/gz/sim/components/<Name>.hh`
  (header-only). Register serialization in `src/ComponentFactory.cc` when
  you want the component to survive log replay / save.
* **System plugins** — `src/systems/<snake_case>/<CamelCase>.{hh,cc}` plus
  an entry in `src/systems/CMakeLists.txt`. Use the `new-system` skill to
  scaffold.
* **High-level wrappers** — `Model`, `Link`, `Joint`, `Light`, `Actor`,
  `Sensor` (`include/gz/sim/`). These wrap an `Entity` plus ECM accessors
  and are usually how user code touches a model.

## Threading model

* `PreUpdate` / `Update` / `PostUpdate` of *different* systems run
  sequentially inside one runner iteration — not in parallel.
* `Server::Run(true, n)` blocks; `Run(false, n)` runs the loop on a worker
  thread. Multi-runner setups exist (different worlds), each on its own
  thread.
* Don't add long-running work in `Update()`. Spawn a thread in `Configure`,
  communicate via lock-free queues, drain in `PreUpdate`.

## Read the source, not just this

If you only have time for two files, read:

1. `include/gz/sim/EntityComponentManager.hh` — every comment matters.
2. `include/gz/sim/System.hh` — the interfaces are tiny and tell you
   exactly what each phase guarantees.