 |
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
|
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
Rules are an advanced query engine for matching against entity graphs. More...
Macros | |
| #define | ecs_rule(world, ...) ecs_rule_init(world, &(ecs_filter_desc_t) __VA_ARGS__ ) |
| Convenience macro for rule creation. More... | |
Functions | |
| FLECS_API ecs_rule_t * | ecs_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_t * | ecs_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... | |
Rules are an advanced query engine for matching against entity graphs.
| #define ecs_rule | ( | world, | |
| ... | |||
| ) | ecs_rule_init(world, &(ecs_filter_desc_t) __VA_ARGS__ ) |
| 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.
| rule | The rule. |
| name | The variable name. |
| FLECS_API void ecs_rule_fini | ( | ecs_rule_t * | rule | ) |
Delete a rule.
| rule | The rule. |
| 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.
| rule | The rule. |
| 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) |
| 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.
| world | The world. |
| rule | The rule. |
| FLECS_API bool ecs_rule_next | ( | ecs_iter_t * | it | ) |
Progress rule iterator.
| it | The iterator. |
| 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 :-)
| it | The iterator. |
| 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.
| rule | The rule. |
| it | The iterator for which to set the variables. |
| expr | The key-value expression. |
| 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.
| rule | The rule. |
| 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
| rule | The rule. |
| FLECS_API int32_t ecs_rule_var_count | ( | const ecs_rule_t * | rule | ) |
Return number of variables in rule.
| rule | The rule. |
| 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.
| rule | The rule. |
| var_id | The variable id. |
| 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.
| rule | The rule. |
| var_id | The variable index. |