ECS

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));
  }
}

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

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