![]() |
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
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_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) |
Systems are a query + function that can be ran manually or by a pipeline.
#define ECS_SYSTEM | ( | world, | |
id, | |||
phase, | |||
... | |||
) |
Declare & define a system.
Example: ECS_SYSTEM(world, Move, EcsOnUpdate, Position, Velocity);
#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 });
#define ECS_SYSTEM_DECLARE | ( | id | ) | ecs_entity_t ecs_id(id) |
#define ECS_SYSTEM_DEFINE | ( | world, | |
id_, | |||
phase, | |||
... | |||
) |
Define a forward declared system.
Example: ECS_SYSTEM_DEFINE(world, Move, EcsOnUpdate, Position, Velocity);
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.
world | The world. |
system | The system from which to obtain the context. |
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.
world | The world. |
system | The system from which to obtain the context. |
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.
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. |
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.
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. |
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.
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. |
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.
world | The world. |
system | The system from which to obtain the query. |