Flecs v3.1
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
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_tecs_system_get_query (const ecs_world_t *world, ecs_entity_t system)
 Get the query object for a system. More...
 
FLECS_API void * ecs_get_system_ctx (const ecs_world_t *world, ecs_entity_t system)
 Get system context. More...
 
FLECS_API void * ecs_get_system_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;
#define ECS_SYSTEM_DEFINE(world, id_, phase,...)
Define a forward declared system.
Definition: system.h:111
ecs_id_t ecs_entity_t
An entity identifier.
Definition: flecs.h:220

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);
const ecs_entity_t EcsDependsOn
Used to express dependency relationships.
FLECS_API ecs_entity_t ecs_system_init(ecs_world_t *world, const ecs_system_desc_t *desc)
Create a system.
ecs_entity_t ecs_entity_init(ecs_world_t *world, const ecs_entity_desc_t *desc)
Find or create an entity.
Used with ecs_entity_init.
Definition: flecs.h:685
const char * name
Name of the entity.
Definition: flecs.h:690
ecs_id_t add[(32)]
Array of ids to add to the new or existing entity.
Definition: flecs.h:716
ecs_entity_t id
Set to modify existing entity (optional)
Definition: flecs.h:688
const char * expr
Filter expression.
Definition: flecs.h:797
ecs_filter_desc_t filter
Filter for the query.
Definition: flecs.h:811
Use with ecs_system_init.
Definition: system.h:38
ecs_iter_action_t callback
Callback that is ran for each result returned by the system's query.
Definition: system.h:64
ecs_entity_t entity
Existing entity to associate with system (optional)
Definition: system.h:42
ecs_query_desc_t query
System query parameters.
Definition: system.h:45

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

FLECS_API void * ecs_get_system_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
worldThe world.
systemThe system from which to obtain the context.
Returns
The context.

◆ ecs_get_system_ctx()

FLECS_API void * ecs_get_system_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
worldThe world.
systemThe system from which to obtain the context.
Returns
The context.

◆ 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 cominbation 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
worldThe world.
systemThe system to run.
delta_timeThe time passed since the last system invocation.
paramA 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
worldThe world.
systemThe system to invoke.
delta_timeThe time passed since the last system invocation.
paramA 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
worldThe world.
systemThe system to run.
stage_currentThe id of the current stage.
stage_countThe total number of stages.
delta_timeThe time passed since the last system invocation.
paramA user-defined parameter to pass to the system.
Returns
handle to last evaluated entity if system was interrupted.

◆ 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
worldThe world.
systemThe system from which to obtain the query.
Returns
The query.