Rules

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

Collaboration diagram for Rules:

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

Functions
FLECS_API ecs_rule_t *	ecs_rule_init (ecs_world_t *world, const ecs_filter_desc_t *desc)
	Create a rule.
FLECS_API void	ecs_rule_fini (ecs_rule_t *rule)
	Delete a rule.
FLECS_API const ecs_filter_t *	ecs_rule_get_filter (const ecs_rule_t *rule)
	Obtain filter from rule.
FLECS_API int32_t	ecs_rule_var_count (const ecs_rule_t *rule)
	Return number of variables in rule.
FLECS_API int32_t	ecs_rule_find_var (const ecs_rule_t *rule, const char *name)
	Find variable index.
FLECS_API const char *	ecs_rule_var_name (const ecs_rule_t *rule, int32_t var_id)
	Get variable name.
FLECS_API bool	ecs_rule_var_is_entity (const ecs_rule_t *rule, int32_t var_id)
	Test if variable is an entity.
FLECS_API ecs_iter_t	ecs_rule_iter (const ecs_world_t *world, const ecs_rule_t *rule)
	Iterate a rule.
FLECS_API bool	ecs_rule_next (ecs_iter_t *it)
	Progress rule iterator.
FLECS_API bool	ecs_rule_next_instanced (ecs_iter_t *it)
	Progress instanced iterator.
FLECS_API char *	ecs_rule_str (const ecs_rule_t *rule)
	Convert rule to a string.
FLECS_API char *	ecs_rule_str_w_profile (const ecs_rule_t *rule, const ecs_iter_t *it)
	Convert rule to string with profile.
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.

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().

Parameters

rule	The rule.
name	The variable name.

Returns

The variable index.

ecs_rule_fini()

FLECS_API void ecs_rule_fini

(

ecs_rule_t *

rule

)

Delete a rule.

Parameters

rule

The 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.

Parameters

rule

The rule.

Returns

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().

Parameters

world	The world.
desc	The descriptor (see ecs_filter_desc_t)

Returns

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.

Parameters

world	The world.
rule	The rule.

Returns

An iterator.

ecs_rule_next()

FLECS_API bool ecs_rule_next

(

ecs_iter_t *

it

)

Progress rule iterator.

Parameters

it	The 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 :-)

Parameters

it	The 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 following format: var_a: value, var_b: value

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

Parameters

rule	The rule.
it	The iterator for which to set the variables.
expr	The 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().

Parameters

rule

The rule.

Returns

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 iteration: it.flags |= EcsIterProfile

Parameters

rule

The rule.

Returns

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.

Parameters

rule

The rule.

Returns

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 application to check if a variable is an entity variable.

Parameters

rule	The rule.
var_id	The 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.

Parameters

rule	The rule.
var_id	The variable index.