Flecs v3.2
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Core API Types

Types for core API objects. More...

Collaboration diagram for Core API Types:

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_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_filter_t ecs_filter_t
 A filter is an iterable data structure that describes a query.
 
typedef struct ecs_query_t ecs_query_t
 A query that caches its results.
 
typedef struct ecs_rule_t ecs_rule_t
 A rule is a query with advanced graph traversal features.
 
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
 
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.
 

Detailed Description

Types for core API objects.

Typedef Documentation

◆ 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.

Definition at line 305 of file flecs.h.

◆ ecs_filter_t

typedef struct ecs_filter_t ecs_filter_t

A filter is an iterable data structure that describes a query.

Filters are used by the various query implementations in Flecs, like queries, observers and rules, to describe a query. Filters themselves can also be iterated.

Definition at line 361 of file flecs.h.

◆ ecs_id_record_t

Information about a (component) id, such as type info and tables with the id.

Definition at line 461 of file flecs.h.

◆ ecs_id_t

typedef uint64_t ecs_id_t

Ids are the things that can be added to an entity.

An id can be an entity or pair, and can have optional id flags.

Definition at line 298 of file flecs.h.

◆ ecs_iter_t

typedef struct ecs_iter_t ecs_iter_t

Definition at line 435 of file flecs.h.

◆ ecs_mixins_t

typedef struct ecs_mixins_t ecs_mixins_t

Type that stores poly mixins.

Definition at line 491 of file flecs.h.

◆ ecs_observable_t

An observable produces events that can be listened for by an observer.

Currently only the world is observable. In the future, queries will become observable objects as well.

Definition at line 428 of file flecs.h.

◆ ecs_observer_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.

Definition at line 423 of file flecs.h.

◆ ecs_poly_t

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:

  • ecs_world_t
  • ecs_stage_t
  • ecs_query_t
  • ecs_filter_t
  • ecs_rule_t
  • (more to come)

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.

Definition at line 488 of file flecs.h.

◆ ecs_query_t

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:

  • Matching is only performed when new tables are created, which is infrequent
  • Iterating a query just walks over the cache, no actual searching is needed
  • Iteration is table-based, which allows for direct iteration of underlying component arrays, providing good cache locality.

While queries are the fastest mechanism to iterate entities, 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.

Definition at line 381 of file flecs.h.

◆ ecs_record_t

typedef struct ecs_record_t ecs_record_t

Information about an entity, like its table and row.

Definition at line 458 of file flecs.h.

◆ ecs_ref_t

typedef struct ecs_ref_t ecs_ref_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.

Definition at line 445 of file flecs.h.

◆ ecs_rule_t

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:

  • Component inheritance
  • Transitivity

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:

  • Up traversal
  • AndFrom, OrFrom, NotFrom operators

Definition at line 403 of file flecs.h.

◆ ecs_table_record_t

Information about where in a table a specific (component) id is stored.

Definition at line 464 of file flecs.h.

◆ ecs_table_t

typedef struct ecs_table_t ecs_table_t

A table stores entities and components for a specific type.

Definition at line 352 of file flecs.h.

◆ ecs_term_t

typedef struct ecs_term_t ecs_term_t

A term is a single element in a query.

Definition at line 355 of file flecs.h.

◆ ecs_type_hooks_t

typedef struct ecs_type_hooks_t ecs_type_hooks_t

Type hooks are callbacks associated with component lifecycle events.

Typical examples of lifecycle events are construction, destruction, copying and moving of components.

Definition at line 450 of file flecs.h.

◆ ecs_type_info_t

typedef struct ecs_type_info_t ecs_type_info_t

Type information.

Contains information about a (component) type, such as its size and alignment and type hooks.

Definition at line 455 of file flecs.h.

◆ ecs_world_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:

  • Ensure to register the same components in each world, in the same order.
  • Create a dummy world in which all components are preregistered which initializes the global id variables.

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.

Definition at line 349 of file flecs.h.