Flecs v3.2
A fast entity component system (ECS) for C & C++
No Matches

Rules are an advanced query engine for matching against entity graphs. More...


#define ecs_rule(world, ...)    ecs_rule_init(world, &(ecs_filter_desc_t) __VA_ARGS__ )
 Convenience macro for rule creation. More...


FLECS_API ecs_rule_tecs_rule_init (ecs_world_t *world, const ecs_filter_desc_t *desc)
 Create a rule. More...
FLECS_API void ecs_rule_fini (ecs_rule_t *rule)
 Delete a rule. More...
FLECS_API const ecs_filter_tecs_rule_get_filter (const ecs_rule_t *rule)
 Obtain filter from rule. More...
FLECS_API int32_t ecs_rule_var_count (const ecs_rule_t *rule)
 Return number of variables in rule. More...
FLECS_API int32_t ecs_rule_find_var (const ecs_rule_t *rule, const char *name)
 Find variable index. More...
FLECS_API const char * ecs_rule_var_name (const ecs_rule_t *rule, int32_t var_id)
 Get variable name. More...
FLECS_API bool ecs_rule_var_is_entity (const ecs_rule_t *rule, int32_t var_id)
 Test if variable is an entity. More...
FLECS_API ecs_iter_t ecs_rule_iter (const ecs_world_t *world, const ecs_rule_t *rule)
 Iterate a rule. More...
FLECS_API bool ecs_rule_next (ecs_iter_t *it)
 Progress rule iterator. More...
FLECS_API bool ecs_rule_next_instanced (ecs_iter_t *it)
 Progress instanced iterator. More...
FLECS_API char * ecs_rule_str (const ecs_rule_t *rule)
 Convert rule to a string. More...
FLECS_API char * ecs_rule_str_w_profile (const ecs_rule_t *rule, const ecs_iter_t *it)
 Convert rule to string with profile. More...
FLECS_API const char * ecs_rule_parse_vars (ecs_rule_t *rule, ecs_iter_t *it, const char *expr)
 Populate variables from key-value string. More...

Detailed Description

Rules are an advanced query engine for matching against entity graphs.

Macro Definition Documentation

◆ ecs_rule

#define ecs_rule (   world,
)     ecs_rule_init(world, &(ecs_filter_desc_t) __VA_ARGS__ )

Convenience macro for rule creation.

Definition at line 32 of file rules.h.

Function Documentation

◆ ecs_rule_find_var()

FLECS_API int32_t ecs_rule_find_var ( const ecs_rule_t rule,
const char *  name 

Find variable index.

This operation looks up the index of a variable in the rule. This index can be used in operations like ecs_iter_set_var and ecs_iter_get_var.

ruleThe rule.
nameThe variable name.
The variable index.

◆ ecs_rule_fini()

FLECS_API void ecs_rule_fini ( ecs_rule_t rule)

Delete a rule.

ruleThe rule.

◆ ecs_rule_get_filter()

FLECS_API const ecs_filter_t * ecs_rule_get_filter ( const ecs_rule_t rule)

Obtain filter from rule.

This operation returns the filter with which the rule was created.

ruleThe rule.
The filter.

◆ ecs_rule_init()

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.

worldThe world.
descThe descriptor (see ecs_filter_desc_t)
The rule.

◆ ecs_rule_iter()

FLECS_API ecs_iter_t ecs_rule_iter ( const ecs_world_t world,
const ecs_rule_t rule 

Iterate a rule.

Note that rule iterators may allocate memory, and that unless the iterator is iterated until completion, it may still hold resources. When stopping iteration before ecs_rule_next has returned false, use ecs_iter_fini to cleanup any remaining resources.

worldThe world.
ruleThe rule.
An iterator.

◆ ecs_rule_next()

FLECS_API bool ecs_rule_next ( ecs_iter_t *  it)

Progress rule iterator.

itThe iterator.

◆ ecs_rule_next_instanced()

FLECS_API bool ecs_rule_next_instanced ( ecs_iter_t *  it)

Progress instanced iterator.

Should not be called unless you know what you're doing :-)

itThe iterator.

◆ ecs_rule_parse_vars()

FLECS_API const char * ecs_rule_parse_vars ( ecs_rule_t rule,
ecs_iter_t *  it,
const char *  expr 

Populate variables from key-value string.

Convenience function to set rule variables from a key-value string separated by comma's. The string must have the followig format: var_a: value, var_b: value

The key-value list may optionally be enclosed in parenthesis.

ruleThe rule.
itThe iterator for which to set the variables.
exprThe key-value expression.

◆ ecs_rule_str()

FLECS_API char * ecs_rule_str ( const ecs_rule_t rule)

Convert rule to a string.

This will convert the rule program to a string which can aid in debugging the behavior of a rule.

The returned string must be freed with ecs_os_free.

ruleThe rule.
The string

◆ ecs_rule_str_w_profile()

FLECS_API char * ecs_rule_str_w_profile ( const ecs_rule_t rule,
const ecs_iter_t *  it 

Convert rule to string with profile.

To use this you must set the EcsIterProfile flag on an iterator before starting uteration: it.flags |= EcsIterProfile

ruleThe rule.
The string

◆ ecs_rule_var_count()

FLECS_API int32_t ecs_rule_var_count ( const ecs_rule_t rule)

Return number of variables in rule.

ruleThe rule.
The number of variables/

◆ ecs_rule_var_is_entity()

FLECS_API bool ecs_rule_var_is_entity ( const ecs_rule_t rule,
int32_t  var_id 

Test if variable is an entity.

Internally the rule engine has entity variables and table variables. When iterating through rule variables (by using ecs_rule_variable_count) only the values for entity variables are accessible. This operation enables an appliction to check if a variable is an entity variable.

ruleThe rule.
var_idThe variable id.

◆ ecs_rule_var_name()

FLECS_API const char * ecs_rule_var_name ( const ecs_rule_t rule,
int32_t  var_id 

Get variable name.

This operation returns the variable name for an index.

ruleThe rule.
var_idThe variable index.