 |
Flecs v4.0
A fast entity component system (ECS) for C & C++
|
|
Flecs v4.0
A fast entity component system (ECS) for C & C++
|
Types for core API objects. More...
Classes | |
| struct | ecs_type_t |
| A type is a list of (component) ids. More... | |
| struct | ecs_header_t |
| Header for ecs_poly_t objects. More... | |
Typedefs | |
| typedef uint64_t | ecs_id_t |
| Ids are the things that can be added to an entity. | |
| typedef ecs_id_t | ecs_entity_t |
| An entity identifier. | |
| typedef struct ecs_world_t | ecs_world_t |
| A world is the container for all ECS data and supporting features. | |
| typedef struct ecs_stage_t | ecs_stage_t |
| A stage enables modification while iterating and from multiple threads. | |
| typedef struct ecs_table_t | ecs_table_t |
| A table stores entities and components for a specific type. | |
| typedef struct ecs_term_t | ecs_term_t |
| A term is a single element in a query. | |
| typedef struct ecs_query_t | ecs_query_t |
| A query returns entities matching a list of constraints. | |
| typedef struct ecs_observer_t | ecs_observer_t |
| An observer is a system that is invoked when an event matches its query. | |
| typedef struct ecs_observable_t | ecs_observable_t |
| An observable produces events that can be listened for by an observer. | |
| typedef struct ecs_iter_t | ecs_iter_t |
| Type used for iterating iterable objects. | |
| typedef struct ecs_ref_t | ecs_ref_t |
| A ref is a fast way to fetch a component for a specific entity. | |
| typedef struct ecs_type_hooks_t | ecs_type_hooks_t |
| Type hooks are callbacks associated with component lifecycle events. | |
| typedef struct ecs_type_info_t | ecs_type_info_t |
| Type information. | |
| typedef struct ecs_record_t | ecs_record_t |
| Information about an entity, like its table and row. | |
| typedef struct ecs_id_record_t | ecs_id_record_t |
| Information about a (component) id, such as type info and tables with the id. | |
| typedef struct ecs_table_record_t | ecs_table_record_t |
| Information about where in a table a specific (component) id is stored. | |
| typedef void | ecs_poly_t |
| A poly object. | |
| typedef struct ecs_mixins_t | ecs_mixins_t |
| Type that stores poly mixins. | |
| typedef struct ecs_header_t | ecs_header_t |
| Header for ecs_poly_t objects. | |
Types for core API objects.
| typedef ecs_id_t ecs_entity_t |
An entity identifier.
Entity ids consist out of a number unique to the entity in the lower 32 bits, and a counter used to track entity liveliness in the upper 32 bits. When an id is recycled, its generation count is increased. This causes recycled ids to be very large (>4 billion), which is normal.
| typedef struct ecs_id_record_t ecs_id_record_t |
| typedef uint64_t ecs_id_t |
| typedef struct ecs_iter_t ecs_iter_t |
| typedef struct ecs_mixins_t ecs_mixins_t |
| typedef struct ecs_observable_t ecs_observable_t |
| typedef struct ecs_observer_t ecs_observer_t |
An observer is a system that is invoked when an event matches its query.
Observers allow applications to respond to specific events, such as adding or removing a component. Observers are created by both specifying a query and a list of event kinds that should be listened for. An example of an observer that triggers when a Position component is added to an entity (in C++):
Observers only trigger when the source of the event matches the full observer query. For example, an OnAdd observer for Position, Velocity will only trigger after both components have been added to the entity.
| typedef void ecs_poly_t |
A poly object.
A poly (short for polymorph) object is an object that has a variable list of capabilities, determined by a mixin table. This is the current list of types in the flecs API that can be used as an ecs_poly_t:
Functions that accept an ecs_poly_t argument can accept objects of these types. If the object does not have the requested mixin the API will throw an assert.
The poly/mixin framework enables partially overlapping features to be implemented once, and enables objects of different types to interact with each other depending on what mixins they have, rather than their type (in some ways it's like a mini-ECS). Additionally, each poly object has a header that enables the API to do sanity checking on the input arguments.
| typedef struct ecs_query_t ecs_query_t |
| typedef struct ecs_record_t ecs_record_t |
A ref is a fast way to fetch a component for a specific entity.
Refs are a faster alternative to repeatedly calling ecs_get() for the same entity/component combination. When comparing the performance of getting a ref to calling ecs_get(), a ref is typically 3-5x faster.
Refs achieve this performance by caching internal data structures associated with the entity and component on the ecs_ref_t object that otherwise would have to be looked up.
| typedef struct ecs_stage_t ecs_stage_t |
| typedef struct ecs_table_record_t ecs_table_record_t |
| typedef struct ecs_table_t ecs_table_t |
| typedef struct ecs_term_t ecs_term_t |
| typedef struct ecs_type_hooks_t ecs_type_hooks_t |
| typedef struct ecs_type_info_t ecs_type_info_t |
| typedef struct ecs_world_t ecs_world_t |
A world is the container for all ECS data and supporting features.
Applications can have multiple worlds, though in most cases will only need one. Worlds are isolated from each other, and can have separate sets of systems, components, modules etc.
If an application has multiple worlds with overlapping components, it is common (though not strictly required) to use the same component ids across worlds, which can be achieved by declaring a global component id variable. To do this in the C API, see the entities/fwd_component_decl example. The C++ API automatically synchronizes component ids between worlds.
Component id conflicts between worlds can occur when a world has already used an id for something else. There are a few ways to avoid this:
In some use cases, typically when writing tests, multiple worlds are created and deleted with different components, registered in different order. To ensure isolation between tests, the C++ API has a flecs::reset function that forces the API to ignore the old component ids.