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
HZ_REFLECT()
ECS_COMPONENT(Velocity) {
v3 value;
};
ECS_TAG(Enemy); // a component with no dataEcsEntity 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:
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));
}
}EcsInreads,EcsInOutwrites,EcsNotexcludes,EcsOptionalmay be missing.EcsResInandEcsResInOutdo the same for resources.- The accessors are checked at compile time: asking for a mutable pointer to something you declared
EcsIndoesn't compile.
Running them
Every frame, schedule your systems inside a scope and flush. All lanes run this code.
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.
WorldTransformis where an entity is. A child (LocalTransform+EcsParent) gets itsWorldTransformfrom its parent: never write a child's directly.- Never call
is_main_thread()orlane_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>/.