System

Systems are a query + function that can be ran manually or by a pipeline. More...

Classes
struct	EcsTickSource
	Component used to provide a tick source to systems. More...
struct	ecs_system_desc_t
	Use with ecs_system_init. More...

Macros
#define	FLECS_SYSTEM_H
#define	ECS_SYSTEM_DECLARE(id)   ecs_entity_t ecs_id(id)
	Forward declare a system. More...
#define	ECS_SYSTEM_DEFINE(world, id_, phase, ...)
	Define a forward declared system. More...
#define	ECS_SYSTEM(world, id, phase, ...)
	Declare & define a system. More...
#define	ecs_system(world, ...)    ecs_system_init(world, &(ecs_system_desc_t) __VA_ARGS__ )
	Shorthand for creating a system with ecs_system_init. More...

Typedefs
typedef struct EcsTickSource	EcsTickSource
	Component used to provide a tick source to systems.
typedef struct ecs_system_desc_t	ecs_system_desc_t
	Use with ecs_system_init.

Functions
FLECS_API ecs_entity_t	ecs_system_init (ecs_world_t *world, const ecs_system_desc_t *desc)
	Create a system.
FLECS_API ecs_entity_t	ecs_run (ecs_world_t *world, ecs_entity_t system, ecs_ftime_t delta_time, void *param)
	Run a specific system manually. More...
FLECS_API ecs_entity_t	ecs_run_worker (ecs_world_t *world, ecs_entity_t system, int32_t stage_current, int32_t stage_count, ecs_ftime_t delta_time, void *param)
	Same as ecs_run, but subdivides entities across number of provided stages. More...
FLECS_API ecs_entity_t	ecs_run_w_filter (ecs_world_t *world, ecs_entity_t system, ecs_ftime_t delta_time, int32_t offset, int32_t limit, void *param)
	Run system with offset/limit and type filter. More...
FLECS_API ecs_query_t *	ecs_system_get_query (const ecs_world_t *world, ecs_entity_t system)
	Get the query object for a system. More...
FLECS_API void *	ecs_system_get_ctx (const ecs_world_t *world, ecs_entity_t system)
	Get system context. More...
FLECS_API void *	ecs_system_get_binding_ctx (const ecs_world_t *world, ecs_entity_t system)
	Get system binding context. More...
FLECS_API void	FlecsSystemImport (ecs_world_t *world)

Detailed Description

Systems are a query + function that can be ran manually or by a pipeline.

Macro Definition Documentation

ECS_SYSTEM

#define ECS_SYSTEM	(		world,
			id,
			phase,
			...
	)

Value:

    ecs_entity_t ecs_id(id) = 0; ECS_SYSTEM_DEFINE(world, id, phase, __VA_ARGS__);\
    ecs_entity_t id = ecs_id(id);\
    (void)ecs_id(id);\
    (void)id

Declare & define a system.

Example: ECS_SYSTEM(world, Move, EcsOnUpdate, Position, Velocity);

Definition at line 131 of file system.h.

ecs_system

#define ecs_system	(		world,
			...
	)		ecs_system_init(world, &(ecs_system_desc_t) __VA_ARGS__ )

Shorthand for creating a system with ecs_system_init.

Example: ecs_system(world, { .entity = ecs_entity(world, { .name = "MyEntity", .add = { ecs_dependson(EcsOnUpdate) } }), .query.filter.terms = { { ecs_id(Position) }, { ecs_id(Velocity) } }, .callback = Move });

Definition at line 152 of file system.h.

ECS_SYSTEM_DECLARE

#define ECS_SYSTEM_DECLARE

(

id

)

ecs_entity_t ecs_id(id)

Forward declare a system.

Definition at line 104 of file system.h.

ECS_SYSTEM_DEFINE

#define ECS_SYSTEM_DEFINE	(		world,
			id_,
			phase,
			...
	)

Value:

    { \
        ecs_system_desc_t desc = {0}; \
        ecs_entity_desc_t edesc = {0}; \
        edesc.id = ecs_id(id_);\
        edesc.name = #id_;\
        edesc.add[0] = ((phase) ? ecs_pair(EcsDependsOn, (phase)) : 0); \
        edesc.add[1] = (phase); \
        desc.entity = ecs_entity_init(world, &edesc);\
        desc.query.filter.expr = #__VA_ARGS__; \
        desc.callback = id_; \
        ecs_id(id_) = ecs_system_init(world, &desc); \
    } \
    ecs_assert(ecs_id(id_) != 0, ECS_INVALID_PARAMETER, NULL)

Define a forward declared system.

Example: ECS_SYSTEM_DEFINE(world, Move, EcsOnUpdate, Position, Velocity);

Definition at line 111 of file system.h.

FLECS_SYSTEM_H

#define FLECS_SYSTEM_H

Definition at line 25 of file system.h.

Function Documentation

ecs_run()

FLECS_API ecs_entity_t ecs_run	(	ecs_world_t *	world,
		ecs_entity_t	system,
		ecs_ftime_t	delta_time,
		void *	param
	)

Run a specific system manually.

This operation runs a single system manually. It is an efficient way to invoke logic on a set of entities, as manual systems are only matched to tables at creation time or after creation time, when a new table is created.

Manual systems are useful to evaluate lists of prematched entities at application defined times. Because none of the matching logic is evaluated before the system is invoked, manual systems are much more efficient than manually obtaining a list of entities and retrieving their components.

An application may pass custom data to a system through the param parameter. This data can be accessed by the system through the param member in the ecs_iter_t value that is passed to the system callback.

Any system may interrupt execution by setting the interrupted_by member in the ecs_iter_t value. This is particularly useful for manual systems, where the value of interrupted_by is returned by this operation. This, in combination with the param argument lets applications use manual systems to lookup entities: once the entity has been found its handle is passed to interrupted_by, which is then subsequently returned.

Parameters

world	The world.
system	The system to run.
delta_time	The time passed since the last system invocation.
param	A user-defined parameter to pass to the system.

Returns

handle to last evaluated entity if system was interrupted.

ecs_run_w_filter()

FLECS_API ecs_entity_t ecs_run_w_filter	(	ecs_world_t *	world,
		ecs_entity_t	system,
		ecs_ftime_t	delta_time,
		int32_t	offset,
		int32_t	limit,
		void *	param
	)

Run system with offset/limit and type filter.

This operation is the same as ecs_run, but filters the entities that will be iterated by the system.

Entities can be filtered in two ways. Offset and limit control the range of entities that is iterated over. The range is applied to all entities matched with the system, thus may cover multiple archetypes.

The type filter controls which entity types the system will evaluate. Only types that contain all components in the type filter will be iterated over. A type filter is only evaluated once per table, which makes filtering cheap if the number of entities is large and the number of tables is small, but not as cheap as filtering in the system signature.

Parameters

world	The world.
system	The system to invoke.
delta_time	The time passed since the last system invocation.
param	A user-defined parameter to pass to the system.

Returns

handle to last evaluated entity if system was interrupted.

ecs_run_worker()

FLECS_API ecs_entity_t ecs_run_worker	(	ecs_world_t *	world,
		ecs_entity_t	system,
		int32_t	stage_current,
		int32_t	stage_count,
		ecs_ftime_t	delta_time,
		void *	param
	)

Same as ecs_run, but subdivides entities across number of provided stages.

Parameters

world	The world.
system	The system to run.
stage_current	The id of the current stage.
stage_count	The total number of stages.
delta_time	The time passed since the last system invocation.
param	A user-defined parameter to pass to the system.

Returns

handle to last evaluated entity if system was interrupted.

ecs_system_get_binding_ctx()

FLECS_API void * ecs_system_get_binding_ctx	(	const ecs_world_t *	world,
		ecs_entity_t	system
	)

Get system binding context.

The binding context is a context typically used to attach any language binding specific data that is needed when invoking a callback that is implemented in another language.

Parameters

world	The world.
system	The system from which to obtain the context.

Returns

The context.

ecs_system_get_ctx()

FLECS_API void * ecs_system_get_ctx	(	const ecs_world_t *	world,
		ecs_entity_t	system
	)

Get system context.

This operation returns the context pointer set for the system. If the provided entity is not a system, the function will return NULL.

Parameters

world	The world.
system	The system from which to obtain the context.

Returns

The context.

ecs_system_get_query()

FLECS_API ecs_query_t * ecs_system_get_query	(	const ecs_world_t *	world,
		ecs_entity_t	system
	)

Get the query object for a system.

Systems use queries under the hood. This enables an application to get access to the underlying query object of a system. This can be useful when, for example, an application needs to enable sorting for a system.

Parameters

world	The world.
system	The system from which to obtain the query.

Returns

The query.