Flecs: Core API Types
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
Core API Types
C API » Core

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_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_component_record_t | ecs_component_record_t
| Information about a (component) id, such as type info and tables with the id.
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.
typedef struct ecs_table_record_t | ecs_table_record_t

## Detailed Description

Types for core API objects.

## Typedef Documentation

## ◆ ecs_component_record_t

typedef struct ecs_component_record_t ecs_component_record_t

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

Definition at line 473 of file flecs.h.

## ◆ ecs_entity_t

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.

Definition at line 361 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 354 of file flecs.h.

## ◆ ecs_iter_t

typedef struct ecs_iter_t ecs_iter_t

Type used for iterating iterable objects.

Iterators are objects that provide applications with information about the currently iterated result, and store any state required for the iteration.

Definition at line 447 of file flecs.h.

## ◆ ecs_mixins_t

typedef struct ecs_mixins_t ecs_mixins_t

Type that stores poly mixins.

Definition at line 497 of file flecs.h.

## ◆ ecs_observable_t

typedef struct ecs_observable_t 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 441 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
});

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 436 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

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 494 of file flecs.h.

## ◆ ecs_query_t

typedef struct ecs_query_t ecs_query_t

A query returns entities matching a list of constraints.

Definition at line 417 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 470 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 457 of file flecs.h.

## ◆ ecs_stage_t

typedef struct ecs_stage_t ecs_stage_t

A stage enables modification while iterating and from multiple threads.

Definition at line 408 of file flecs.h.

## ◆ ecs_table_record_t

typedef struct ecs_table_record_t ecs_table_record_t

Definition at line 506 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 411 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 414 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 462 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 467 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 405 of file flecs.h.