# ECS

> Entities, components and systems that run on every core, scheduled from what they read and write.

Kaigen's ECS is where your game lives. Entities are ids, components are plain structs, and systems are functions that run over every entity with the components they ask for. Systems say what they read and write, and the scheduler uses that to run them on every lane, in the right order, without data races.

Every engine system (rendering, physics, transforms, animation, audio) is also an ECS module, so your game and the engine work on the same data.

## Components and entities

Components:

```
HZ_REFLECT()
ECS_COMPONENT(Velocity) {
  v3 value;
};

ECS_TAG(Enemy); // a component with no data
```

Entities:

```
EcsEntity e = ecs_entity_create(world);
ecs_component_set(world, e, Velocity, {.value = {0, 0, 1}});
ecs_component_add(world, e, Enemy);
```

**Resources** are components that belong to the world instead of an entity: the game clock, the score, the input. `ecs_resource_set(world, Score, {0})` adds one, and systems ask for it like any other component.

## Systems

A system declares its terms, then loops over the entities that match:

A system:

```
ecs_system(enemy_move_system, EcsIn(Enemy), EcsIn(Velocity), EcsInOut(WorldTransform),
           EcsResIn(GameClock)) {
  const GameClock *clock = ecs_sys_get_resource(GameClock);
  for (i32 i = 0; i < it->count; i++) {
    const Velocity *v = ecs_sys_get_component(Velocity, i);
    WorldTransform *t = ecs_sys_get_component_mut(WorldTransform, i);
    f32 dt = it->delta_time * clock->speed;
    t->position = v3_add(t->position, v3_scale(v->value, dt));
  }
}
```

- `EcsIn` reads, `EcsInOut` writes, `EcsNot` excludes, `EcsOptional` may be missing. `EcsResIn` and `EcsResInOut` do the same for resources.
- The accessors are checked at compile time: asking for a mutable pointer to something you declared `EcsIn` doesn't compile.

## Running them

Every frame, schedule your systems inside a scope and flush. All lanes run this code.

The frame:

```
ecs_scope(world) {
  ecs_schedule(world, enemy_move_system);
  ecs_schedule_single(world, score_system); // writes a resource: one task
  ecs_transform_schedule(world);
  ecs_renderer_schedule(world);
  ecs_flush(world, dt);
}
```

`ecs_schedule` splits the matching entities across every lane. A system that writes a resource can't do that (the resource is one value they'd all share), so it's scheduled with `ecs_schedule_single` and runs as one task, while the other lanes keep working. The compiler tells you when you got this wrong.

The order you schedule in is the order data flows: a system that reads what another writes runs after it.

## Talking between systems

There's no event bus. Something that happened is state on the entity it happened to: a flag, a counter, or a tag you add (`Dying`) so the entity starts matching other systems. If many entities produce something shared (damage dealt, a score), write it to each entity's own component, and let one `ecs_schedule_single` system gather the ones that changed.

`ecs_iter_changed(it)` lets that gather skip the whole frame when nothing changed.

## Worth knowing

- Creating and destroying entities inside a system is deferred until the end of the flush.
- `WorldTransform` is where an entity is. A child (`LocalTransform` + `EcsParent`) gets its `WorldTransform` from its parent: never write a child's directly.
- Never call `is_main_thread()` or `lane_sync()` inside a scope. Schedule a system instead.
- `--commands "1:dump_world;2:quit"` prints every table and system, and how many entities each system matched. When a system "doesn't run", look there first.

Everything is in `hz/src/engine/ecs/ecs.h`, and each engine module has its bridge in `hz/src/engine/ecs/<module>/`.
