 |
Flecs v3.2
A fast entity component system (ECS) for C & C++
|
|
Flecs v3.2
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. More... | |
| typedef ecs_id_t | ecs_entity_t |
| An entity identifier. More... | |
| typedef struct ecs_world_t | ecs_world_t |
| A world is the container for all ECS data and supporting features. More... | |
| typedef struct ecs_table_t | ecs_table_t |
| A table stores entities and components for a specific type. More... | |
| typedef struct ecs_term_t | ecs_term_t |
| A term is a single element in a query. More... | |
| typedef struct ecs_filter_t | ecs_filter_t |
| A filter is an iterable data structure that describes a query. More... | |
| typedef struct ecs_query_t | ecs_query_t |
| A query that caches its results. More... | |
| typedef struct ecs_rule_t | ecs_rule_t |
| A rule is a query with advanced graph traversal features. More... | |
| typedef struct ecs_observer_t | ecs_observer_t |
| An observer is a system that is invoked when an event matches its query. More... | |
| typedef struct ecs_observable_t | ecs_observable_t |
| An observable produces events that can be listened for by an observer. More... | |
| typedef struct ecs_iter_t | ecs_iter_t |
| typedef struct ecs_ref_t | ecs_ref_t |
| A ref is a fast way to fetch a component for a specific entity. More... | |
| typedef struct ecs_type_hooks_t | ecs_type_hooks_t |
| Type hooks are callbacks associated with component lifecycle events. More... | |
| typedef struct ecs_type_info_t | ecs_type_info_t |
| Type information. More... | |
| typedef struct ecs_record_t | ecs_record_t |
| Information about an entity, like its table and row. More... | |
| typedef struct ecs_id_record_t | ecs_id_record_t |
| Information about a (component) id, such as type info and tables with the id. More... | |
| typedef struct ecs_table_record_t | ecs_table_record_t |
| Information about where in a table a specific (component) id is stored. More... | |
| typedef void | ecs_poly_t |
| A poly object. More... | |
| typedef struct ecs_mixins_t | ecs_mixins_t |
| Type that stores poly mixins. More... | |
| 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_filter_t ecs_filter_t |
| typedef struct ecs_id_record_t ecs_id_record_t |
| typedef uint64_t ecs_id_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++):
world.observer<Position>() .event(flecs::OnAdd) .each([](Position& p) { // called when Position is added to an entity });
Observer queries can be as complex as filters. 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 |
A query that caches its results.
Queries are the fastest mechanism for finding and iterating over entities. Queries cache results as a list of matching tables (vs. individual entities).
This has several advantages:
While queries are the fastest mechanism to iterate entiites, they are slower to create than other mechanisms, as a result of having to build the cache first. For this reason queries are best suited for use cases where a single query can be reused many times (like is the case for systems).
For ad-hoc queries it is recommended to use filters or rules instead, which are slower to iterate, but much faster to create. Applications should at all times avoid frequent creation/deletion of queries.
| 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_rule_t ecs_rule_t |
A rule is a query with advanced graph traversal features.
Rules are fast uncached queries with support for advanced graph features such as the usage of query variables. A simple example of a rule that matches all spaceship entities docked to a planet: SpaceShip, (DockedTo, $planet), Planet($planet)
Here, the rule traverses the DockedTo relationship, and matches Planet on the target of this relationship. Through the usage of variables rules can match arbitrary patterns against entity graphs. Other features supported exclusively by rules are:
Rules have similar iteration performance to filters, but are slower than queries. Rules and filters will eventually be merged into a single query implementation. Features still lacking for rules are:
| 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.