Function ecs_rule_init

Synopsis

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

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

Description

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, do this: desc.terms[0].obj.name = "_X";

or

desc.terms[0].obj.name = "X"; desc.terms[0].obj.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.

Parameters

world - The world.

desc - The descriptor (see ecs_filter_desc_t)

Returns
The rule.

Source

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