Flecs v4.0
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Macros
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)    ecs_entity_t id, ecs_id(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)   ECS_ENTITY_DEFINE(world, id, 0)
 Define a forward declared tag.
 
#define ECS_TAG(world, id)   ECS_ENTITY(world, id, 0)
 Declare & define a tag.
 
#define ECS_PREFAB_DECLARE   ECS_DECLARE
 Forward declare a prefab.
 
#define ECS_PREFAB_DEFINE(world, id, ...)   ECS_ENTITY_DEFINE(world, id, Prefab, __VA_ARGS__)
 Define a forward declared prefab.
 
#define ECS_PREFAB(world, id, ...)   ECS_ENTITY(world, id, Prefab, __VA_ARGS__)
 Declare & define a prefab.
 
#define ECS_COMPONENT_DECLARE(id)   ecs_entity_t ecs_id(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)   ecs_entity_t ecs_id(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)   ecs_query_t* 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, ...)    ecs_entity_init(world, &(ecs_entity_desc_t) __VA_ARGS__ )
 Shorthand for creating an entity with ecs_entity_init().
 
#define ecs_component(world, ...)    ecs_component_init(world, &(ecs_component_desc_t) __VA_ARGS__ )
 Shorthand for creating a component with ecs_component_init().
 
#define ecs_component_t(world, T)
 Shorthand for creating a component from a type.
 
#define ecs_query(world, ...)    ecs_query_init(world, &(ecs_query_desc_t) __VA_ARGS__ )
 Shorthand for creating a query with ecs_query_cache_init.
 
#define ecs_observer(world, ...)    ecs_observer_init(world, &(ecs_observer_desc_t) __VA_ARGS__ )
 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:339

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,
... )    ecs_component_init(world, &(ecs_component_desc_t) __VA_ARGS__ )

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)    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_component_init
ecs_entity_t ecs_component_init(ecs_world_t *world, const ecs_component_desc_t *desc)
Find or create a component.
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
Used with ecs_component_init().
Definition flecs.h:977
ecs_component_desc_t::type
ecs_type_info_t type
Parameters for type (size, hooks, ...)
Definition flecs.h:984
ecs_component_desc_t::entity
ecs_entity_t entity
Existing entity to associate with observer (optional)
Definition flecs.h:981
ecs_entity_desc_t
Used with ecs_entity_init().
Definition flecs.h:901
ecs_entity_desc_t::name
const char * name
Name of the entity.
Definition flecs.h:908
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:929
ecs_entity_desc_t::symbol
const char * symbol
Optional entity symbol.
Definition flecs.h:919
ecs_entity_desc_t::id
ecs_entity_t id
Set to modify existing entity (optional)
Definition flecs.h:904
ecs_type_info_t::alignment
ecs_size_t alignment
Alignment of type.
Definition flecs.h:881
ecs_type_info_t::size
ecs_size_t size
Size of type.
Definition flecs.h:880

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_component_t

#define ecs_component_t ( world,
T )
Value:
ecs_component_init(world, &(ecs_component_desc_t) { \
.entity = ecs_entity(world, { \
.name = #T, \
.symbol = #T, \
.use_low_id = true \
}), \
.type.size = ECS_SIZEOF(T), \
.type.alignment = ECS_ALIGNOF(T) \
})
ecs_entity
#define ecs_entity(world,...)
Shorthand for creating an entity with ecs_entity_init().
Definition flecs_c.h:235

Shorthand for creating a component from a type.

Example:

ecs_component_t(world, Position);
ecs_component_t
#define ecs_component_t(world, T)
Shorthand for creating a component from a type.
Definition flecs_c.h:260

Definition at line 260 of file flecs_c.h.

◆ ECS_DECLARE

#define ECS_DECLARE ( id)     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,
... )    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"
});

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:940

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,
... )    ecs_observer_init(world, &(ecs_observer_desc_t) __VA_ARGS__ )

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:293

Definition at line 293 of file flecs_c.h.

◆ ECS_OBSERVER_DECLARE

#define ECS_OBSERVER_DECLARE ( id)    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_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:1212
ecs_observer_desc_t::entity
ecs_entity_t entity
Existing entity to associate with observer (optional)
Definition flecs.h:1217
ecs_observer_desc_t::events
ecs_entity_t events[(8)]
Events to observe (OnAdd, OnRemove, OnSet)
Definition flecs.h:1223
ecs_observer_desc_t::query
ecs_query_desc_t query
Query for observer.
Definition flecs.h:1220
ecs_observer_desc_t::callback
ecs_iter_action_t callback
Callback to invoke on an event, invoked when the observer matches.
Definition flecs.h:1230
ecs_query_desc_t::expr
const char * expr
Query DSL expression (optional)
Definition flecs.h:1146

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,
... )   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,
... )   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:760

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,
... )    ecs_query_init(world, &(ecs_query_desc_t) __VA_ARGS__ )

Shorthand for creating a query with ecs_query_cache_init.

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

Definition at line 278 of file flecs_c.h.

◆ ECS_QUERY_DECLARE

#define ECS_QUERY_DECLARE ( name)    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_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:1138
ecs_query_desc_t::entity
ecs_entity_t entity
Entity associated with query (optional)
Definition flecs.h:1205

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