System

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

Collaboration diagram for System:

Classes
struct	EcsTickSource
	Component used to provide a tick source to systems. More...
struct	ecs_system_desc_t
	Use with ecs_system_init() to create or update a system. More...
struct	ecs_system_t
	System type, get with ecs_system_get(). More...

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

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() to create or update a system.
typedef struct ecs_system_t	ecs_system_t
	System type, get with ecs_system_get().

Functions
FLECS_API ecs_entity_t	ecs_system_init (ecs_world_t *world, const ecs_system_desc_t *desc)
	Create a system.
FLECS_API const ecs_system_t *	ecs_system_get (const ecs_world_t *world, ecs_entity_t system)
	Get a system object.
FLECS_API void	ecs_system_set_group (ecs_world_t *world, ecs_entity_t system, uint64_t group_id)
	Set query group for 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.
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 a number of provided stages.
FLECS_API void	FlecsSystemImport (ecs_world_t *world)
	System module import function.

Detailed Description

Systems are a query + function that can be run 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 and define a system.

Example:

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

Definition at line 240 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_ids( ecs_dependson(EcsOnUpdate) )
  }),
  .query.terms = {
    { ecs_id(Position) },
    { ecs_id(Velocity) }
  },
  .callback = Move
});

Definition at line 264 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 208 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_;\
        desc.entity = ecs_entity_init(world, &edesc);\
        desc.query.expr = #__VA_ARGS__; \
        desc.phase = phase_; \
        desc.callback = id_; \
        ecs_id(id_) = ecs_system_init(world, &desc); \
    } \
    ecs_assert(ecs_id(id_) != 0, ECS_INVALID_PARAMETER, "failed to create system %s", #id_)

Define a forward-declared system.

Example:

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

Definition at line 218 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 pre-matched 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 the last evaluated entity if the 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 a 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 the last evaluated entity if the system was interrupted.

ecs_system_get()

FLECS_API const ecs_system_t * ecs_system_get	(	const ecs_world_t *	world,
		ecs_entity_t	system )

Get a system object.

Return the system object. Can be used to access various information about the system, like the query and context.

Parameters

world	The world.
system	The system.

Returns

The system object.

ecs_system_init()

FLECS_API ecs_entity_t ecs_system_init	(	ecs_world_t *	world,
		const ecs_system_desc_t *	desc )

Create a system.

Parameters

world	The world.
desc	The system descriptor.

Returns

The system entity.

ecs_system_set_group()

FLECS_API void ecs_system_set_group	(	ecs_world_t *	world,
		ecs_entity_t	system,
		uint64_t	group_id )

Set query group for system.

This operation configures a system created with a grouped query to only iterate results for the specified group ID. The group filter is applied to both manual runs and pipeline execution.

Parameters

world	The world.
system	The system.
group_id	The query group ID to iterate.

FlecsSystemImport()

FLECS_API void FlecsSystemImport

(

ecs_world_t *

world

)

System module import function.

Usage:

ECS_IMPORT(world, FlecsSystem)

Parameters

world

The world.