Cookbook

Minimal World

C

ecs_init();
ecs_entity_t entity = ecs_new();
ecs_fini();

C++

ecs::init();
auto entity = ecs::entity::create();

Game Loop With Time

C

ECS_RESOURCE(Time, { float dt; });
ECS_COMPONENT(Position, { float x; });
ECS_COMPONENT(Velocity, { float x; });

static void Move(ecs_iter_t *it) {
    const Time *time = ecs_get_resource_read(it->world, Time);
    Position *p = ecs_field(it, 0);
    const Velocity *v = ecs_field(it, 1);
    for (uint32_t i = 0; i < it->count; i++) p[i].x += v[i].x * time->dt;
}

C++

struct Time { float dt; };
struct Position { float x; };
struct Velocity { float x; };

ecs::set_resource(Time{ .dt = 0.016f });
ecs::system("Move").each([](ecs::res<const Time> time,
                              Position &p, const Velocity &v) {
    p.x += v.x * time->dt;
});

Parent And Child

C

ecs_entity_t parent = ecs_new();
ecs_entity_t child = ecs_new();
ecs_set(child, ChildOf, { parent });

C++

auto parent = ecs::entity::create();
auto child = ecs::entity::create().child_of(parent);

ChildOf cascades deletion: killing the parent also kills its children.

Optional Component Query

C

ecs_query_id_t q = ecs_query({
    .terms = { ecs_inout(Position), ecs_in_optional(Velocity) },
});

C++

auto query = ecs::query()
    .require<Position>()
    .each([](Position &position) {
        // Query optional data through the C API when needed.
        (void)position;
    });

React To A Component Set

C

static void OnPositionSet(ecs_observer_event_t *event) {
    const Position *incoming = event->trigger_data;
    (void)incoming;
}

ecs_observer({
    .on = EcsOnSet,
    .query.terms = { ecs_in(Position) },
    .callback = OnPositionSet,
});

C++

ecs::observe<ecs::OnSet>().each([](const Position &position) {
    std::cout << position.x << '\n';
});

Pause Entities With Disabled

C

ecs_add(entity, Disabled);
ecs_remove(entity, Disabled);

C++

entity.disable();
entity.enable();

Normal queries skip disabled entities. Add ecs_filter(Disabled) to match them explicitly.