Function ecs_query_set_group


#include <include/flecs.h>

FLECS_API void ecs_query_set_group(ecs_iter_t *it, uint64_t group_id)


Set group to iterate for query iterator. This operation limits the results returned by the query to only the selected group id. The query must have a group_by function, and the iterator must be a query iterator.

Groups are sets of tables that are stored together in the query cache based on a group id, which is calculated per table by the group_by function. To iterate a group, an iterator only needs to know the first and last cache node for that group, which can both be found in a fast O(1) operation.

As a result, group iteration is one of the most efficient mechanisms to filter out large numbers of entities, even if those entities are distributed across many tables. This makes it a good fit for things like dividing up a world into cells, and only iterating cells close to a player.

The group to iterate must be set before the first call to ecs_query_next. No operations that can add/remove components should be invoked between calling ecs_query_set_group and ecs_query_next.


it - The query iterator.

group_id - The group to iterate.


Line 3448 in include/flecs.h.