Flecs: Creation macro's
Description: A fast entity component system (ECS) for C & C++

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

Loading...
Searching...
No Matches
Creation macro's
C API » Macro API

Convenience macro's for creating entities, components and observers. More...

Collaboration diagram for Creation macro's:

## Macros
#define | ECS_DECLARE(id)
#define | ECS_ENTITY_DECLARE ECS_DECLARE
| Forward declare an entity.
#define | ECS_ENTITY_DEFINE(world, id_, ...)
| Define a forward declared entity.
#define | ECS_ENTITY(world, id, ...)
| Declare & define an entity.
#define | ECS_TAG_DECLARE ECS_DECLARE
| Forward declare a tag.
#define | ECS_TAG_DEFINE(world, id)
| Define a forward declared tag.
#define | ECS_TAG(world, id)
| Declare & define a tag.
#define | ECS_PREFAB_DECLARE ECS_DECLARE
| Forward declare a prefab.
#define | ECS_PREFAB_DEFINE(world, id, ...)
| Define a forward declared prefab.
#define | ECS_PREFAB(world, id, ...)
| Declare & define a prefab.
#define | ECS_COMPONENT_DECLARE(id)
| Forward declare a component.
#define | ECS_COMPONENT_DEFINE(world, id_)
| Define a forward declared component.
#define | ECS_COMPONENT(world, id)
| Declare & define a component.
#define | ECS_OBSERVER_DECLARE(id)
#define | ECS_OBSERVER_DEFINE(world, id_, kind, ...)
| Define a forward declared observer.
#define | ECS_OBSERVER(world, id, kind, ...)
| Declare & define an observer.
#define | ECS_QUERY_DECLARE(name)
#define | ECS_QUERY_DEFINE(world, name_, ...)
| Define a forward declared observer.
#define | ECS_QUERY(world, name, ...)
| Declare & define an observer.
#define | ecs_entity(world, ...)
| Shorthand for creating an entity with ecs_entity_init().
#define | ecs_component(world, ...)
| Shorthand for creating a component with ecs_component_init().
#define | ecs_query(world, ...)
| Shorthand for creating a query with ecs_query_cache_init.
#define | ecs_observer(world, ...)
| Shorthand for creating an observer with ecs_observer_init().

## Detailed Description

Convenience macro's for creating entities, components and observers.

## Macro Definition Documentation

## ◆ ECS_COMPONENT

#define ECS_COMPONENT | ( |  | world,
|  |  | id )

Value:
ecs_entity_t ecs_id(id) = 0;\
ECS_COMPONENT_DEFINE(world, id);\
(void)ecs_id(id)
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component id for EcsDocDescription.
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:361

Declare & define a component.

Example:

ECS_COMPONENT(world, Position);
ECS_COMPONENT
#define ECS_COMPONENT(world, id)
Declare & define a component.
Definition flecs_c.h:145

Definition at line 145 of file flecs_c.h.

## ◆ ecs_component

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

Value:
ecs_component_init(world, &(ecs_component_desc_t) __VA_ARGS__ )
ecs_component_init
ecs_entity_t ecs_component_init(ecs_world_t *world, const ecs_component_desc_t *desc)
Find or create a component.
ecs_component_desc_t
Used with ecs_component_init().
Definition flecs.h:1094

Shorthand for creating a component with ecs_component_init().

Example:

ecs_component(world, {
.type.size = 4,
.type.alignment = 4
});
ecs_component
#define ecs_component(world,...)
Shorthand for creating a component with ecs_component_init().
Definition flecs_c.h:249

Definition at line 249 of file flecs_c.h.

## ◆ ECS_COMPONENT_DECLARE

#define ECS_COMPONENT_DECLARE | ( |  | id | ) |

Value:
ecs_entity_t ecs_id(id)

Forward declare a component.

Definition at line 112 of file flecs_c.h.

## ◆ ECS_COMPONENT_DEFINE

#define ECS_COMPONENT_DEFINE | ( |  | world,
|  |  | id_ )

Value:
{\
ecs_component_desc_t desc = {0}; \
ecs_entity_desc_t edesc = {0}; \
edesc.id = ecs_id(id_); \
edesc.use_low_id = true; \
edesc.name = #id_; \
edesc.symbol = #id_; \
desc.entity = ecs_entity_init(world, &edesc); \
desc.type.size = ECS_SIZEOF(id_); \
desc.type.alignment = ECS_ALIGNOF(id_); \
ecs_id(id_) = ecs_component_init(world, &desc);\
}\
ecs_assert(ecs_id(id_) != 0, ECS_INVALID_PARAMETER, "failed to create component %s", #id_)
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_component_desc_t::type
ecs_type_info_t type
Parameters for type (size, hooks, ...)
Definition flecs.h:1101
ecs_component_desc_t::entity
ecs_entity_t entity
Existing entity to associate with observer (optional)
Definition flecs.h:1098
ecs_entity_desc_t
Used with ecs_entity_init().
Definition flecs.h:1018
ecs_entity_desc_t::name
const char * name
Name of the entity.
Definition flecs.h:1025
ecs_entity_desc_t::use_low_id
bool use_low_id
When set to true, a low id (typically reserved for components) will be used to create the entity,...
Definition flecs.h:1046
ecs_entity_desc_t::symbol
const char * symbol
Optional entity symbol.
Definition flecs.h:1036
ecs_entity_desc_t::id
ecs_entity_t id
Set to modify existing entity (optional)
Definition flecs.h:1021
ecs_type_info_t::alignment
ecs_size_t alignment
Alignment of type.
Definition flecs.h:997
ecs_type_info_t::size
ecs_size_t size
Size of type.
Definition flecs.h:996

Define a forward declared component.

Example:

ECS_COMPONENT_DEFINE(world, Position);
ECS_COMPONENT_DEFINE
#define ECS_COMPONENT_DEFINE(world, id_)
Define a forward declared component.
Definition flecs_c.h:122

Definition at line 122 of file flecs_c.h.

## ◆ ECS_DECLARE

#define ECS_DECLARE | ( |  | id | ) |

Value:
ecs_entity_t id, ecs_id(id)

Definition at line 25 of file flecs_c.h.

## ◆ ECS_ENTITY

#define ECS_ENTITY | ( |  | world,
|  |  | id,
|  |  | ... )

Value:
ecs_entity_t ecs_id(id); \
ecs_entity_t id = 0; \
ECS_ENTITY_DEFINE(world, id, __VA_ARGS__)

Declare & define an entity.

Example:

ECS_ENTITY(world, MyEntity, Position, Velocity);
ECS_ENTITY
#define ECS_ENTITY(world, id,...)
Declare & define an entity.
Definition flecs_c.h:60

Definition at line 60 of file flecs_c.h.

## ◆ ecs_entity

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

Value:
ecs_entity_init(world, &(ecs_entity_desc_t) __VA_ARGS__ )

Shorthand for creating an entity with ecs_entity_init().

Example:

ecs_entity(world, {
.name = "MyEntity"
});
ecs_entity
#define ecs_entity(world,...)
Shorthand for creating an entity with ecs_entity_init().
Definition flecs_c.h:235

Definition at line 235 of file flecs_c.h.

## ◆ ECS_ENTITY_DECLARE

#define ECS_ENTITY_DECLARE ECS_DECLARE

Forward declare an entity.

Definition at line 29 of file flecs_c.h.

## ◆ ECS_ENTITY_DEFINE

#define ECS_ENTITY_DEFINE | ( |  | world,
|  |  | id_,
|  |  | ... )

Value:
{ \
ecs_entity_desc_t desc = {0}; \
desc.id = id_; \
desc.name = #id_; \
desc.add_expr = #__VA_ARGS__; \
id_ = ecs_entity_init(world, &desc); \
ecs_id(id_) = id_; \
ecs_assert(id_ != 0, ECS_INVALID_PARAMETER, "failed to create entity %s", #id_); \
} \
(void)id_; \
(void)ecs_id(id_)
ecs_entity_desc_t::add_expr
const char * add_expr
String expression with components to add.
Definition flecs.h:1057

Define a forward declared entity.

Example:

ECS_ENTITY_DEFINE(world, MyEntity, Position, Velocity);
ECS_ENTITY_DEFINE
#define ECS_ENTITY_DEFINE(world, id_,...)
Define a forward declared entity.
Definition flecs_c.h:39

Definition at line 39 of file flecs_c.h.

## ◆ ECS_OBSERVER

#define ECS_OBSERVER | ( |  | world,
|  |  | id,
|  |  | kind,
|  |  | ... )

Value:
ecs_entity_t ecs_id(id) = 0; \
ECS_OBSERVER_DEFINE(world, id, kind, __VA_ARGS__);\
ecs_entity_t id = ecs_id(id);\
(void)ecs_id(id);\
(void)id

Declare & define an observer.

Example:

ECS_OBSERVER(world, AddPosition, EcsOnAdd, Position);
EcsOnAdd
const ecs_entity_t EcsOnAdd
Event that triggers when an id is added to an entity.
ECS_OBSERVER
#define ECS_OBSERVER(world, id, kind,...)
Declare & define an observer.
Definition flecs_c.h:183

Definition at line 183 of file flecs_c.h.

## ◆ ecs_observer

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

Value:
ecs_observer_init(world, &(ecs_observer_desc_t) __VA_ARGS__ )
ecs_observer_init
ecs_entity_t ecs_observer_init(ecs_world_t *world, const ecs_observer_desc_t *desc)
Create observer.
ecs_observer_desc_t
Used with ecs_observer_init().
Definition flecs.h:1325

Shorthand for creating an observer with ecs_observer_init().

Example:

ecs_observer(world, {
.terms = {{ ecs_id(Position) }},
.events = { EcsOnAdd },
.callback = AddPosition
});
ecs_observer
#define ecs_observer(world,...)
Shorthand for creating an observer with ecs_observer_init().
Definition flecs_c.h:274

Definition at line 274 of file flecs_c.h.

## ◆ ECS_OBSERVER_DECLARE

#define ECS_OBSERVER_DECLARE | ( |  | id | ) |

Value:
ecs_entity_t ecs_id(id)

Definition at line 151 of file flecs_c.h.

## ◆ ECS_OBSERVER_DEFINE

#define ECS_OBSERVER_DEFINE | ( |  | world,
|  |  | id_,
|  |  | kind,
|  |  | ... )

Value:
{\
ecs_observer_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.callback = id_;\
desc.query.expr = #__VA_ARGS__;\
desc.events[0] = kind;\
ecs_id(id_) = ecs_observer_init(world, &desc);\
ecs_assert(ecs_id(id_) != 0, ECS_INVALID_PARAMETER, "failed to create observer %s", #id_);\
}
ecs_observer_desc_t::entity
ecs_entity_t entity
Existing entity to associate with observer (optional)
Definition flecs.h:1330
ecs_observer_desc_t::query
ecs_query_desc_t query
Query for observer.
Definition flecs.h:1333
ecs_observer_desc_t::callback
ecs_iter_action_t callback
Callback to invoke on an event, invoked when the observer matches.
Definition flecs.h:1343
ecs_observer_desc_t::events
ecs_entity_t events[8]
Events to observe (OnAdd, OnRemove, OnSet)
Definition flecs.h:1336
ecs_query_desc_t::expr
const char * expr
Query DSL expression (optional)
Definition flecs.h:1259

Define a forward declared observer.

Example:

ECS_OBSERVER_DEFINE(world, AddPosition, EcsOnAdd, Position);
ECS_OBSERVER_DEFINE
#define ECS_OBSERVER_DEFINE(world, id_, kind,...)
Define a forward declared observer.
Definition flecs_c.h:161

Definition at line 161 of file flecs_c.h.

## ◆ ECS_PREFAB

#define ECS_PREFAB | ( |  | world,
|  |  | id,
|  |  | ... )

Value:
ECS_ENTITY(world, id, Prefab, __VA_ARGS__)

Declare & define a prefab.

Example:

ECS_PREFAB(world, MyPrefab, Position, Velocity);
ECS_PREFAB
#define ECS_PREFAB(world, id,...)
Declare & define a prefab.
Definition flecs_c.h:109

Definition at line 109 of file flecs_c.h.

## ◆ ECS_PREFAB_DECLARE

#define ECS_PREFAB_DECLARE ECS_DECLARE

Forward declare a prefab.

Definition at line 89 of file flecs_c.h.

## ◆ ECS_PREFAB_DEFINE

#define ECS_PREFAB_DEFINE | ( |  | world,
|  |  | id,
|  |  | ... )

Value:
ECS_ENTITY_DEFINE(world, id, Prefab, __VA_ARGS__)

Define a forward declared prefab.

Example:

ECS_PREFAB_DEFINE(world, MyPrefab, Position, Velocity);
ECS_PREFAB_DEFINE
#define ECS_PREFAB_DEFINE(world, id,...)
Define a forward declared prefab.
Definition flecs_c.h:99

Definition at line 99 of file flecs_c.h.

## ◆ ECS_QUERY

#define ECS_QUERY | ( |  | world,
|  |  | name,
|  |  | ... )

Value:
ecs_query_t* name = NULL; \
ECS_QUERY_DEFINE(world, name, __VA_ARGS__);\
(void)name
ecs_query_t
Queries are lists of constraints (terms) that match entities.
Definition flecs.h:813

Declare & define an observer.

Example:

ECS_OBSERVER(world, AddPosition, EcsOnAdd, Position);

Definition at line 220 of file flecs_c.h.

## ◆ ecs_query

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

Value:
ecs_query_init(world, &(ecs_query_desc_t) __VA_ARGS__ )
ecs_query_init
ecs_query_t * ecs_query_init(ecs_world_t *world, const ecs_query_desc_t *desc)
Create a query.
ecs_query_desc_t
Used with ecs_query_init().
Definition flecs.h:1251

Shorthand for creating a query with ecs_query_cache_init.

Example: ecs_query(world, { .terms = {{ ecs_id(Position) }} });

Definition at line 259 of file flecs_c.h.

## ◆ ECS_QUERY_DECLARE

#define ECS_QUERY_DECLARE | ( |  | name | ) |

Value:
ecs_query_t* name

Definition at line 191 of file flecs_c.h.

## ◆ ECS_QUERY_DEFINE

#define ECS_QUERY_DEFINE | ( |  | world,
|  |  | name_,
|  |  | ... )

Value:
{\
ecs_query_desc_t desc = {0};\
ecs_entity_desc_t edesc = {0}; \
edesc.name = #name_; \
desc.entity = ecs_entity_init(world, &edesc); \
desc.expr = #__VA_ARGS__;\
name_ = ecs_query_init(world, &desc);\
ecs_assert(name_ != NULL, ECS_INVALID_PARAMETER, "failed to create query %s", #name_);\
}
ecs_query_desc_t::entity
ecs_entity_t entity
Entity associated with query (optional)
Definition flecs.h:1318

Define a forward declared observer.

Example:

ECS_QUERY_DEFINE(world, AddPosition, Position);
ECS_QUERY_DEFINE
#define ECS_QUERY_DEFINE(world, name_,...)
Define a forward declared observer.
Definition flecs_c.h:201

Definition at line 201 of file flecs_c.h.

## ◆ ECS_TAG

#define ECS_TAG | ( |  | world,
|  |  | id )

Value:
ECS_ENTITY(world, id, 0)

Declare & define a tag.

Example:

ECS_TAG(world, MyTag);
ECS_TAG
#define ECS_TAG(world, id)
Declare & define a tag.
Definition flecs_c.h:86

Definition at line 86 of file flecs_c.h.

## ◆ ECS_TAG_DECLARE

#define ECS_TAG_DECLARE ECS_DECLARE

Forward declare a tag.

Definition at line 66 of file flecs_c.h.

## ◆ ECS_TAG_DEFINE

#define ECS_TAG_DEFINE | ( |  | world,
|  |  | id )

Value:
ECS_ENTITY_DEFINE(world, id, 0)

Define a forward declared tag.

Example:

ECS_TAG_DEFINE(world, MyTag);
ECS_TAG_DEFINE
#define ECS_TAG_DEFINE(world, id)
Define a forward declared tag.
Definition flecs_c.h:76

Definition at line 76 of file flecs_c.h.