Function ecs_rule_init


#include <include/flecs/addons/rules.h>

FLECS_API ecs_rule_t * ecs_rule_init(ecs_world_t *world, const ecs_filter_desc_t *desc)


Create a rule. A rule accepts the same descriptor as a filter, but has the additional ability to use query variables.

Query variables can be used to constrain wildcards across multiple terms to the same entity. Regular ECS queries do this in a limited form, as querying for Position, Velocity only returns entities that have both components.

Query variables expand this to constrain entities that are resolved while the query is being matched. Consider a query for all entities and the mission they are on: (Mission, *)

If an entity is on multiple missions, the wildcard will match it multiple times. Now say we want to only list combat missions. Naively we could try: (Mission, *), CombatMission(*)

But this doesn't work, as term 1 returns entities with missions, and term 2 returns all combat missions for all entities. Query variables make it possible to apply CombatMission to the found mission: (Mission, $M), CombatMission($M)

By using the same variable ('M') we ensure that CombatMission is applied to the mission found in the current result.

Variables can be used in each part of the term (predicate, subject, object). This is a valid query: Likes($X, $Y), Likes($Y, $X)

This is also a valid query: _Component, Serializable(_Component)

In the query expression syntax, variables are prefixed with a $. When using the descriptor, specify the variable kind: desc.terms[0].second = { .name = "X", .var = EcsVarIsVariable }

Different terms with the same variable name are automatically correlated by the query engine.

A rule needs to be explicitly deleted with ecs_rule_fini.


world - The world.

desc - The descriptor (see ecs_filter_desc_t)

The rule.

Mentioned in


Line 74 in include/flecs/addons/rules.h.