Flecs: System
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
System
C API » Addons

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)
| 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, ...)
| 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
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component ID for EcsDocDescription.
ECS_SYSTEM_DEFINE
#define ECS_SYSTEM_DEFINE(world, id_, phase_,...)
Define a forward-declared system.
Definition system.h:218
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:381

Declare and define a system.

Example:

ECS_SYSTEM(world, Move, EcsOnUpdate, Position, Velocity);
EcsOnUpdate
const ecs_entity_t EcsOnUpdate
OnUpdate pipeline phase.
ECS_SYSTEM
#define ECS_SYSTEM(world, id, phase,...)
Declare and define a system.
Definition system.h:240

Definition at line 240 of file system.h.

## ◆ ecs_system

#define ecs_system | ( |  | world,
|  |  | ... )

Value:
ecs_system_init(world, &(ecs_system_desc_t) __VA_ARGS__ )
ecs_system_init
FLECS_API ecs_entity_t ecs_system_init(ecs_world_t *world, const ecs_system_desc_t *desc)
Create a system.
ecs_system_desc_t
Use with ecs_system_init() to create or update a system.
Definition system.h:38

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
});
ecs_system
#define ecs_system(world,...)
Shorthand for creating a system with ecs_system_init().
Definition system.h:264
ecs_entity
#define ecs_entity(world,...)
Shorthand for creating an entity with ecs_entity_init().
Definition flecs_c.h:235
ecs_dependson
#define ecs_dependson(e)
Construct a DependsOn pair.
Definition flecs_c.h:926
ecs_ids
#define ecs_ids(...)
Convenience macro for creating a compound literal ID array.
Definition flecs_c.h:765

Definition at line 264 of file system.h.

## ◆ ECS_SYSTEM_DECLARE

#define ECS_SYSTEM_DECLARE | ( |  | id | ) |

Value:
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_)
ECS_INVALID_PARAMETER
#define ECS_INVALID_PARAMETER
Invalid parameter error code.
Definition log.h:661
ecs_entity_init
ecs_entity_t ecs_entity_init(ecs_world_t *world, const ecs_entity_desc_t *desc)
Find or create an entity.
ecs_entity_desc_t
Used with ecs_entity_init().
Definition flecs.h:1042
ecs_entity_desc_t::name
const char * name
Name of the entity.
Definition flecs.h:1049
ecs_entity_desc_t::id
ecs_entity_t id
Set to modify existing entity (optional).
Definition flecs.h:1045
ecs_query_desc_t::expr
const char * expr
Query DSL expression (optional).
Definition flecs.h:1283
ecs_system_desc_t::phase
ecs_entity_t phase
Optional pipeline phase for the system to run in.
Definition system.h:49
ecs_system_desc_t::callback
ecs_iter_action_t callback
Callback that is run for each result returned by the system's query.
Definition system.h:54
ecs_system_desc_t::entity
ecs_entity_t entity
Existing entity to associate with the system (optional).
Definition system.h:42
ecs_system_desc_t::query
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 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)
ECS_IMPORT
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:125

Parameters

  world | The world.