C API

Basic API types

typedef uint64_t ecs_entity_t

An entity identifier.

Mentioned in:

Readme / Example

Quickstart / Entities

Quickstart / Components

Quickstart / Traits

Manual / Entity

Manual / Component

Manual / Tag

Manual / System

Manual / Phase

Manual / Pipeline

Manual / Trigger

Manual / Type

Manual / Scope

Manual / Naming conventions

Manual / Macro's

Manual / Entities

Manual / Named entities

Manual / Generations

Manual / Basic usage

Manual / Advanced usage

Manual / Type roles

Manual / Components

Manual / Global component handles

Manual / Local component handles

Manual / Component disabling

Manual / Tag handles

Manual / Switchable tags

Manual / OWNED

Manual / PARENT

Manual / Entity

Manual / Nothing

Manual / Sorting

Manual / Sorting by entity id

Manual / Monitors

Manual / OnSet Systems

Manual / Modules

Manual / Hierarchies

Manual / Iteration

Manual / Path identifiers

Manual / Scoping

Manual / Paths and signatures

Manual / Instancing

Manual / Overriding

Manual / Automatic overriding

Manual / Instance hierarchies

Manual / Prefabs

Manual / Traits

Manual / Traits and queries

Manual / Pair tags

Manual / Pair encoding

Manual / Deferred operations

Manual / Staging

MigrationGuide / API changes

typedef uint64_t ecs_id_t

An id. Ids are the things that can be added to an entity. An id can be an entity or pair, and can have an optional role.

typedef const ecs_vector_t * ecs_type_t

A vector containing component identifiers used to describe a type.

Mentioned in:

Manual / Macro's

Manual / Basic usage

Manual / Advanced usage

Manual / Local component handles

Manual / Tag handles

Manual / Filters

typedef struct ecs_world_t ecs_world_t

An ECS world is the container for all ECS data and supporting features.

Mentioned in:

Readme / Example

Quickstart / World

Quickstart / Components

Quickstart / Tags

Manual / Naming conventions

Manual / Components

Manual / Global component handles

Manual / Local component handles

Manual / Component disabling

Manual / Tagging

Manual / Tag handles

Manual / Modules

typedef struct ecs_query_t ecs_query_t

Queries are the primary mechanism for iterating (prematched) entities.

Mentioned in:

Quickstart / Queries

Manual / Queries

Manual / SHARED

Manual / ANY

Manual / PARENT

Manual / CASCADE

Manual / Entity

Manual / Singleton

Manual / Nothing

Manual / Optional

Manual / Sorting

Manual / Hierarchical queries

Manual / Traits and queries

typedef struct ecs_iter_t ecs_iter_t

Mentioned in:

typedef struct ecs_ref_t ecs_ref_t

Refs cache data that lets them access components faster than ecs_get.

ecs_match_kind_tDescribes how a filter should match components with a table.
ecs_filter_tFilters alllow for ad-hoc quick filtering of entity tables.
ecs_world_info_tType that contains information about the world.

Function Types

typedef void(* ecs_iter_action_t)(ecs_iter_t *it)

Action callback for systems and triggers

typedef bool(* ecs_iter_next_action_t)(ecs_iter_t *it)

typedef int(* ecs_compare_action_t)(ecs_entity_t e1, const void *ptr1, ecs_entity_t e2, const void *ptr2)

Compare callback used for sorting

typedef int32_t(* ecs_rank_type_action_t)(ecs_world_t *world, ecs_entity_t rank_component, ecs_type_t type)

Compare callback used for sorting

typedef void(* ecs_module_action_t)(ecs_world_t *world)

Initialization action for modules

typedef void(* ecs_fini_action_t)(ecs_world_t *world, void *ctx)

Action callback on world exit

Builtin Types

EcsNameEntity name.
EcsComponentComponent information.
EcsTypeComponent that stores an ecs_type_t
EcsComponentLifecycleComponent that contains lifecycle callbacks for a component.
EcsTriggerComponent used for registering component triggers

Type Roles

ECS_ROLE (1ull << 63)

Role bit added to roles to differentiate between roles and generations

ECS_CASE (ECS_ROLE | (0x7Cull << 56))

Cases are used to switch between mutually exclusive components

Mentioned in:

Manual / Type roles

Manual / Switchable tags

ECS_SWITCH (ECS_ROLE | (0x7Bull << 56))

Switches allow for fast switching between mutually exclusive components

Mentioned in:

Manual / Type roles

Manual / Switchable tags

ECS_PAIR (ECS_ROLE | (0x7Aull << 56))

The PAIR role indicates that the entity is a pair identifier.

Mentioned in:

Manual / Pair encoding

ECS_OWNED (ECS_ROLE | (0x75ull << 56))

Enforce ownership of a component

Mentioned in:

Manual / Type roles

Manual / Automatic overriding

ECS_DISABLED (ECS_ROLE | (0x74ull << 56))

Track whether component is enabled or not

Builtin Tags

EcsModule (ECS_HI_COMPONENT_ID + 0)

EcsPrefab (ECS_HI_COMPONENT_ID + 1)

Mentioned in:

EcsHidden (ECS_HI_COMPONENT_ID + 2)

EcsDisabled (ECS_HI_COMPONENT_ID + 3)

Mentioned in:

EcsDisabledIntern (ECS_HI_COMPONENT_ID + 4)

EcsInactive (ECS_HI_COMPONENT_ID + 5)

EcsOnDemand (ECS_HI_COMPONENT_ID + 6)

EcsMonitor (ECS_HI_COMPONENT_ID + 7)

Mentioned in:

EcsPipeline (ECS_HI_COMPONENT_ID + 8)

EcsOnAdd (ECS_HI_COMPONENT_ID + 9)

Mentioned in:

EcsOnRemove (ECS_HI_COMPONENT_ID + 10)

Mentioned in:

EcsOnSet (ECS_HI_COMPONENT_ID + 11)

Mentioned in:

EcsUnSet (ECS_HI_COMPONENT_ID + 12)

Mentioned in:

EcsPreFrame (ECS_HI_COMPONENT_ID + 13)

EcsOnLoad (ECS_HI_COMPONENT_ID + 14)

Mentioned in:

EcsPostLoad (ECS_HI_COMPONENT_ID + 15)

Mentioned in:

EcsPreUpdate (ECS_HI_COMPONENT_ID + 16)

Mentioned in:

EcsOnUpdate (ECS_HI_COMPONENT_ID + 17)

Mentioned in:

EcsOnValidate (ECS_HI_COMPONENT_ID + 18)

Mentioned in:

EcsPostUpdate (ECS_HI_COMPONENT_ID + 19)

Mentioned in:

EcsPreStore (ECS_HI_COMPONENT_ID + 20)

Mentioned in:

EcsOnStore (ECS_HI_COMPONENT_ID + 21)

Mentioned in:

EcsPostFrame (ECS_HI_COMPONENT_ID + 22)

EcsFlecs (ECS_HI_COMPONENT_ID + 23)

Builtin entity ids

EcsFlecsCore (ECS_HI_COMPONENT_ID + 24)

EcsWorld (ECS_HI_COMPONENT_ID + 25)

Mentioned in:

EcsWildcard (ECS_HI_COMPONENT_ID + 27)

EcsThis (ECS_HI_COMPONENT_ID + 28)

EcsTransitive (ECS_HI_COMPONENT_ID + 29)

EcsFinal (ECS_HI_COMPONENT_ID + 30)

EcsChildOf (ECS_HI_COMPONENT_ID + 31)

Mentioned in:

EcsIsA (ECS_HI_COMPONENT_ID + 32)

Mentioned in:

EcsLastInternalComponentId (ecs_id(EcsSystem))

EcsFirstUserComponentId (32)

EcsFirstUserEntityId (ECS_HI_COMPONENT_ID + 32)

Mentioned in:

Convenience Macro's

ECS_CTOR(type,var,...)
ECS_XTOR_IMPL(type, ctor, var, __VA_ARGS__)

Declare a component. Example: ECS_COMPONENT(world, Position); Declare an extern component variable. Use this macro in a header when defining a component identifier globally. Must be used together with ECS_COMPONENT_DECLARE.

Example: ECS_COMPONENT_EXTERN(Position); Declare a component variable outside the scope of a function. Use this macro in a header when defining a component identifier globally. Must be used together with ECS_COMPONENT_DEFINE.

Example: ECS_COMPONENT_IMPL(Position); Define a component, store in variable outside of the current scope. Use this macro in a header when defining a component identifier globally. Must be used together with ECS_COMPONENT_DECLARE.

Example: ECS_COMPONENT_DEFINE(world, Position); Declare a tag. Example: ECS_TAG(world, MyTag); Declare an extern tag variable. Use this macro in a header when defining a tag identifier globally. Must be used together with ECS_TAG_DECLARE.

Example: ECS_TAG_EXTERN(Enemy); Declare a tag variable outside the scope of a function. Use this macro in a header when defining a tag identifier globally. Must be used together with ECS_TAG_DEFINE.

Example: ECS_TAG_DECLARE(Enemy); Define a tag, store in variable outside of the current scope. Use this macro in a header when defining a tag identifier globally. Must be used together with ECS_TAG_DECLARE.

Example: ECS_TAG_DEFINE(world, Enemy); Declare a constructor. Example: ECS_CTOR(MyType, ptr, { ptr->value = NULL; });

Mentioned in:

Quickstart / Component Lifecycle

ECS_DTOR(type,var,...)
ECS_XTOR_IMPL(type, dtor, var, __VA_ARGS__)

Declare a destructor. Example: ECS_DTOR(MyType, ptr, { free(ptr->value); });

Mentioned in:

Quickstart / Component Lifecycle

ECS_COPY(type,dst_var,src_var,...)
ECS_COPY_IMPL(type, dst_var, src_var, __VA_ARGS__)

Declare a copy action. Example: ECS_COPY(MyType, dst, src, { dst->value = strdup(src->value); });

Mentioned in:

Quickstart / Component Lifecycle

ECS_MOVE(type,dst_var,src_var,...)
ECS_MOVE_IMPL(type, dst_var, src_var, __VA_ARGS__)

Declare a move action. Example: ECS_MOVE(MyType, dst, src, { dst->value = src->value; src->value = 0; });

Mentioned in:

Quickstart / Component Lifecycle

ecs_ctor(type)
type##_ctor

Mentioned in:

ecs_dtor(type)
type##_dtor

Mentioned in:

ecs_copy(type)
type##_copy

Mentioned in:

ecs_move(type)
type##_move

Mentioned in:

World API

ecs_initCreate a new world
ecs_miniSame as ecs_init, but with minimal set of modules loaded.
ecs_init_w_argsCreate a new world with arguments
ecs_finiDelete a world
ecs_atfiniRegister action to be executed when world is destroyed
ecs_run_post_frameRegister action to be executed once after frame
ecs_quitSignal exit This operation signals that the application should quit
ecs_should_quitReturn whether a quit has been signaled.
ecs_set_component_actions_w_idRegister ctor, dtor, copy & move actions for component.

ecs_set_component_actions(world,component,...)
ecs_set_component_actions_w_id(world, ecs_id(component), &(EcsComponentLifecycle)__VA_ARGS__)

Mentioned in:

ecs_set_contextSet a world context
ecs_get_contextGet the world context
ecs_get_world_infoGet world info.
ecs_dimDimension the world for a specified number of entities
ecs_set_entity_rangeSet a range for issueing new entity ids
ecs_enable_range_checkEnable/disable range limits
ecs_enable_lockingEnable world locking while in progress
ecs_lockLocks the world
ecs_unlockUnlocks the world
ecs_begin_waitWait until world becomes available
ecs_end_waitRelease world after calling ecs_begin_wait
ecs_tracing_enableEnable or disable tracing
ecs_measure_frame_timeMeasure frame time
ecs_measure_system_timeMeasure system time
ecs_set_target_fpsSet target frames per second (FPS) for application
ecs_get_threadsGet current number of threads.

Creating Entities

ecs_new_idCreate new entity id
ecs_new_component_idCreate new component id
ecs_new_w_idCreate new entity
ecs_bulk_new_w_idCreate a new entity
ecs_bulk_new_w_dataCreate N new entities and initialize components
ecs_cloneCreate N new entities

Adding & Removing

ecs_add_idAdd an entity to an entity
ecs_remove_idAdd a component, type or tag to an entity

Enabling & Disabling components.

Remove a component, type or tag from an entity. This operation removes a type to an entity. The resulting type of the entity will be the difference of the previous type and the provided type. If the type did not overlap with the entity type, this operation has no side effects.

This operation accepts variables declared by ECS_COMPONENT, ECS_TYPE and ECS_TAG.

Parameters

world - The world.

entity - The entity.

component - The component, type or tag to remove.

ecs_enable_component_w_idEnable or disable component

ecs_enable_component(world,entity,T,enable)
ecs_enable_component_w_id(world, entity, ecs_id(T), enable)

Mentioned in:

ecs_is_component_enabled_w_idTest if component is enabled

ecs_is_component_enabled(world,entity,T)
ecs_is_component_enabled_w_id(world, entity, ecs_id(T))

Mentioned in:

Pairs

ecs_new_w_pair(world,relation,object)
ecs_new_w_id(world, ecs_pair(relation, object))

Create entity with pair. This operation creates a new entity with a pair. A pair is a combination of a relation and an object, can can be used to store relationships between entities. Example:

subject = Alice, relation = Likes, object = Bob

This operation accepts regular entities. For passing in component identifiers use ecs_typeid, like this:

ecs_new_w_pair(world, ecs_id(relation), object)

Parameters

world - The world.

relation - The relation part of the pair to add.

object - The object part of the pair to add.

Returns
The new entity.
Mentioned in:

Manual / Type roles

Manual / OWNED

Manual / PARENT

Manual / Hierarchies

Manual / Instancing

Manual / Overriding

Manual / Automatic overriding

Manual / Instance hierarchies

MigrationGuide / API changes

ecs_add_pair(world,subject,relation,object)
ecs_add_id(world, subject, ecs_pair(relation, object))

Add a pair. This operation adds a pair to an entity. A pair is a combination of a relation and an object, can can be used to store relationships between entities. Example:

subject = Alice, relation = Likes, object = Bob

This operation accepts regular entities. For passing in component identifiers use ecs_typeid, like this:

ecs_add_pair(world, subject, ecs_id(relation), object)

Parameters

world - The world.

subject - The entity to which to add the pair.

relation - The relation part of the pair to add.

object - The object part of the pair to add.

Mentioned in:

Manual / Type roles

Manual / Hierarchies

ecs_remove_pair(world,subject,relation,object)
ecs_remove_id(world, subject, ecs_pair(relation, object))

Remove a pair. This operation removes a pair from an entity. A pair is a combination of a relation and an object, can can be used to store relationships between entities. Example:

subject = Alice, relation = Likes, object = Bob

This operation accepts regular entities. For passing in component identifiers use ecs_typeid, like this:

ecs_remove_pair(world, subject, ecs_id(relation), object)

Parameters

world - The world.

subject - The entity from which to remove the pair.

relation - The relation part of the pair to remove.

object - The object part of the pair to remove.

ecs_has_pair(world,subject,relation,object)
ecs_has_id(world, subject, ecs_pair(relation, object))

Test for a pair. This operation tests if an entity has a pair. This operation accepts regular entities. For passing in component identifiers use ecs_typeid, like this:

ecs_has_pair(world, subject, ecs_id(relation), object)

Parameters

world - The world.

subject - The entity from which to remove the pair.

relation - The relation part of the pair to remove.

object - The object part of the pair to remove.

ecs_set_pair(world,subject,relation,object,...)
ecs_set_ptr_w_id(world, subject,
ecs_pair(ecs_id(relation), object),
sizeof(relation), &(relation)__VA_ARGS__)

Set relation of pair. This operation sets data for a pair, where the relation determines the type. A pair is a combination of a relation and an object, can can be used to store relationships between entities.

Pairs can contain data if either the relation or object of the pair are a component. If both are a component, the relation takes precedence.

If this operation is used with a pair where the relation is not a component, it will fail. The object part of the pair expects a regular entity. To pass a component as object, use ecs_typeid like this:

ecs_set_pair(world, subject, relation, ecs_id(object))

Parameters

world - The world.

subject - The entity on which to set the pair.

relation - The relation part of the pair. This must be a component.

object - The object part of the pair.

ecs_set_pair_object(world,subject,relation,object,...)
ecs_set_ptr_w_id(world, subject,
ecs_pair(relation, ecs_id(object)),
sizeof(object), &(object)__VA_ARGS__)

Set object of pair. This operation sets data for a pair, where the object determines the type. A pair is a combination of a relation and an object, can can be used to store relationships between entities.

Pairs can contain data if either the relation or object of the pair are a component. If both are a component, the relation takes precedence.

If this operation is used with a pair where the object is not a component, it will fail. The relation part of the pair expects a regular entity. To pass a component as relation, use ecs_typeid like this:

ecs_set_pair_object(world, subject, ecs_id(relation), object)

Parameters

world - The world.

subject - The entity.

relation - The relation part of the pair.

object - The object part of the pair. This must be a component.

ecs_get_mut_pair(world,subject,relation,object,is_added)
((relation*)ecs_get_mut_w_id(world, subject,
ecs_pair(ecs_id(relation), object), is_added))

ecs_get_mut_pair_object(world,subject,relation,object,is_added)
((object*)ecs_get_mut_w_id(world, subject,
ecs_pair(relation, ecs_id(object)), is_added))

ecs_modified_pair(world,subject,relation,object)
ecs_modified_w_id(world, subject, ecs_pair(relation, object))

ecs_get_pair(world,subject,relation,object)
((relation*)ecs_get_w_id(world, subject,
ecs_pair(ecs_id(relation), object)))

Get relation of pair. This operation obtains the value of a pair, where the relation determines the type. A pair is a combination of a relation and an object, can can be used to store relationships between entities.

Pairs can contain data if either the relation or object of the pair are a component. If both are a component, the relation takes precedence.

If this operation is used with a pair where the relation is not a component, it will fail. The object part of the pair expects a regular entity. To pass a component as relation, use ecs_typeid like this:

ecs_get_pair(world, subject, relation, ecs_id(object))

Parameters

world - The world.

subject - The entity.

relation - The relation part of the pair. Must be a component.

object - The object part of the pair.

ecs_get_pair_object(world,subject,relation,object)
((object*)ecs_get_w_id(world, subject,
ecs_pair(relation, ecs_id(object))))

Get object of pair. This operation obtains the value of a pair, where the object determines the type. A pair is a combination of a relation and an object, can can be used to store relationships between entities.

Pairs can contain data if either the relation or object of the pair are a component. If both are a component, the relation takes precedence.

If this operation is used with a pair where the object is not a component, it will fail. The relation part of the pair expects a regular entity. To pass a component as relation, use ecs_typeid like this:

ecs_get_pair_object(world, subject, ecs_id(relation), object)

Parameters

world - The world.

subject - The entity.

relation - The relation part of the pair. Must be a component.

object - The object part of the pair.

Deleting Entities and components

ecs_clearClear all components
ecs_deleteDelete an entity
ecs_delete_childrenDelete children of an entity

Getting Components

ecs_get_w_idGet an immutable pointer to a component

ecs_get(world,entity,component)
((const component*)ecs_get_w_id(world, entity, ecs_id(component)))

Get an immutable pointer to a component. Same as ecs_get_w_id, but accepts the typename of a component.

Parameters

world - The world.

entity - The entity.

id - The component to obtain.

Returns
The component pointer, NULL if the entity does not have the component.
Mentioned in:

Quickstart / Components

Quickstart / Tags

Manual / Macro's

Manual / Performance guidelines

Manual / Flecs guidelines

Manual / Components

Manual / Local component handles

Manual / Instancing

Manual / Overriding

Manual / Instance hierarchies

MigrationGuide / Staging

MigrationGuide / API changes

ecs_get_ref_w_idGet an immutable reference to a component

ecs_get_ref(world,ref,entity,component)
((const component*)ecs_get_ref_w_id(world, ref, entity, ecs_id(component)))

Get an immutable reference to a component. Same as ecs_get_ref_w_id, but accepts the typename of a component.

Parameters

world - The world.

ref - Pointer to a ecs_ref_t value. Must be initialized.

entity - The entity.

id - The component to obtain.

Returns
The component pointer, NULL if the entity does not have the component.
Mentioned in:

Manual / Flecs guidelines

ecs_get_caseGet case for switch

Setting Components

ecs_get_mut_w_idGet a mutable pointer to a component

ecs_get_mut(world,entity,component,is_added)
((component*)ecs_get_mut_w_id(world, entity, ecs_id(component), is_added))

Get a mutable pointer to a component. Same as ecs_get_mut_w_id but accepts a component typename.

Parameters

world - The world.

entity - The entity.

id - The component to obtain.

is_added - Out parameter that returns true if the component was added.

Returns
The component pointer.
Mentioned in:

Quickstart / Components

Manual / Components

Manual / Deferred operations

MigrationGuide / Staging

MigrationGuide / API changes

ecs_modified_w_idSignal that a component has been modified

ecs_modified(world,entity,component)
ecs_modified_w_id(world, entity, ecs_id(component))

Signal that a component has been modified. Same as ecs_modified_w_id but accepts a component typename.

Parameters

world - The world.

entity - The entity.

id - The component that was modified.

Mentioned in:

Manual / Components

ecs_set_ptr_w_idSet the value of a component

ecs_set_ptr(world,entity,component,ptr)
ecs_set_ptr_w_id(world, entity, ecs_id(component), sizeof(component), ptr)

Set the value of a component. Same as ecs_set_ptr_w_id, but accepts a component typename and automatically determines the type size.

Parameters

world - The world.

entity - The entity.

component - The component to set.

size - The size of the pointer to the value.

Returns
The entity. A new entity if no entity was provided.

ecs_set(world,entity,component,...)
ecs_set_ptr_w_id(world, entity, ecs_id(component), sizeof(component), &(component)__VA_ARGS__)

Set the value of a component. Same as ecs_set_ptr, but accepts a value instead of a pointer to a value.

Parameters

world - The world.

entity - The entity.

component - The component to set.

size - The size of the pointer to the value.

Returns
The entity. A new entity if no entity was provided.
Mentioned in:

Readme / Example

FAQ / How do I attach resources to a system?

Quickstart / Components

Quickstart / Tags

Designing with Flecs / Annotations

Manual / Idempotence

Manual / Entity names

Manual / Macro's

Manual / Named entities

Manual / Advanced usage

Manual / Components

Manual / Local component handles

Manual / SYSTEM

Manual / Entity

Manual / Singleton

Manual / Sorting

Manual / OnSet Systems

Manual / Instancing

Manual / Overriding

Manual / Automatic overriding

Manual / Instance hierarchies

Manual / Pair tags

Manual / Deferred operations

Manual / Staging

MigrationGuide / API changes

Singleton components

ecs_singleton_get(world,comp)
ecs_get(world, ecs_id(comp), comp)

ecs_singleton_set(world,comp,...)
ecs_set(world, ecs_id(comp), comp, __VA_ARGS__)

Mentioned in:

ecs_singleton_get_mut(world,comp)
ecs_get_mut(world, ecs_id(comp), comp, NULL)

ecs_singleton_modified(world,comp)
ecs_modified(world, ecs_id(comp), comp)

Testing Components

ecs_has_idTest if an entity has an entity

Entity Metadata

Test if an entity has a component, type or tag. This operation returns true if the entity has the provided component, type or tag in its type.

Parameters

world - The world.

entity - The entity.

type - The component, type or tag to test for.

Returns
True if the entity has the type, false if not. Test if an entity owns an entity. This operation is similar to ecs_has, but will return false if the entity does not own the entity, which is the case if the entity is defined on a base entity with an INSTANCEOF role.
Parameters

world - The world.

entity - The entity.

type - The entity to test for.

Returns
True if the entity owns the entity, false if not.

ecs_is_validTest whether an entity is valid
ecs_is_aliveTest whether an entity is alive.
ecs_get_aliveGet alive identifier
ecs_ensureEnsure id is alive
ecs_existsTest whether an entity exists
ecs_get_typeGet the type of an entity.
ecs_get_typeidGet the typeid of an entity.
ecs_get_nameGet the name of an entity
ecs_role_strConvert type role to string
ecs_id_strConvert id to string
ecs_get_object_w_idGet the object of an entity

ecs_get_object(world,entity,rel,component)
ecs_get_parent_w_id(world, entity, ecs_id(component))

Get the parent of an entity. Same as ecs_get_parent_w_id but accepts a component typename.

Parameters

world - The world.

entity - The entity.

rel - The relation between the entity and the object.

component - A component that the parent must have.

Returns
The parent of the entity, 0 if no parent was found.
ecs_enableEnable or disable an entity
ecs_count_idCount entities that have the specified id

ecs_count(world,type)
ecs_count_type(world, ecs_type(type))

Count entities that have a component, type or tag. Returns the number of entities that have the specified component, type or tag.

Parameters

world - The world.

type - The component, type or tag.

Returns
The number of entities that have the component, type or tag.
ecs_count_filterCount entities that match a filter

Lookups

ecs_lookupLookup an entity by name
ecs_lookup_childLookup a child entity by name
ecs_lookup_path_w_sepLookup an entity from a path

ecs_lookup_path(world,parent,path)
ecs_lookup_path_w_sep(world, parent, path, ".", NULL)

Lookup an entity from a path. Same as ecs_lookup_path_w_sep, but with defaults for the separator and prefix. These defaults are used when looking up identifiers in a type or signature expression.

Parameters

world - The world.

parent - The entity from which to resolve the path.

path - The path to resolve.

Returns
The entity if found, else 0.
Mentioned in:

Manual / Path identifiers

Manual / Instance hierarchies

MigrationGuide / API changes

ecs_lookup_fullpath(world,path)
ecs_lookup_path_w_sep(world, 0, path, ".", NULL)

Lookup an entity from a full path. Same as ecs_lookup_pat, but searches from the current scope, or root scope if no scope is set.

Parameters

world - The world.

path - The path to resolve.

Returns
The entity if found, else 0.
Mentioned in:

Manual / Modules

Manual / Path identifiers

Manual / Scoping

ecs_lookup_symbolLookup an entity by its symbol name
ecs_use

Paths

ecs_get_path_w_sepGet a path identifier for an entity

ecs_get_path(world,parent,child)
ecs_get_path_w_sep(world, parent, child, 0, ".", NULL)

Get a path identifier for an entity. Same as ecs_get_path_w_sep, but with default values for the separator and prefix. These defaults are used throughout Flecs whenever identifiers are used in type or signature expressions.

Parameters

world - The world.

parent - The entity from which to create the path.

child - The entity to which to create the path.

Returns
The relative entity path.

ecs_get_fullpath(world,child)
ecs_get_path_w_sep(world, 0, child, 0, ".", NULL)

Get a full path for an entity. Same as ecs_get_path, but with default values for the separator and prefix, and the path is created from the current scope, or root if no scope is provided.

Parameters

world - The world.

child - The entity to which to create the path.

Returns
The entity path.
Mentioned in:

Manual / Memory ownership

Manual / Iteration

Manual / Path identifiers

ecs_new_from_path_w_sepFind or create entity from path

ecs_new_from_path(world,parent,path)
ecs_new_from_path_w_sep(world, parent, path, ".", NULL)

Find or create entity from path. Same as ecs_new_from_path_w_sep, but with defaults for sep and prefix.

Parameters

world - The world.

parent - The entity relative to which the entity should be created.

path - The path to create the entity for.

Returns
The entity.

ecs_new_from_fullpath(world,path)
ecs_new_from_path_w_sep(world, 0, path, ".", NULL)

Find or create entity from full path. Same as ecs_new_from_path, but entity will be created from the current scope, or root scope if no scope is set.

Parameters

world - The world.

path - The path to create the entity for.

Returns
The entity.
ecs_add_path_w_sepAdd specified path to entity

ecs_add_path(world,entity,parent,path)
ecs_add_path_w_sep(world, entity, parent, path, ".", NULL)

Add specified path to entity. Same as ecs_add_from_path_w_sep, but with defaults for sep and prefix.

Parameters

world - The world.

entity - The entity to which to add the path.

parent - The entity relative to which the entity should be created.

path - The path to create the entity for.

Returns
The entity.

ecs_add_fullpath(world,entity,path)
ecs_add_path_w_sep(world, entity, 0, path, ".", NULL)

Add specified path to entity. Same as ecs_add_from_path, but entity will be created from the current scope, or root scope if no scope is set.

Parameters

world - The world.

entity - The entity to which to add the path.

path - The path to create the entity for.

Returns
The entity.

Scopes

ecs_get_child_countDoes entity have children.
ecs_scope_iterReturn a scope iterator
ecs_scope_iter_w_filterReturn a filtered scope iterator
ecs_scope_nextProgress the scope iterator
ecs_set_scopeSet the current scope
ecs_get_scopeGet the current scope
ecs_set_name_prefixSet a name prefix for newly created entities

Filters

ecs_filter_iterReturn a filter iterator
ecs_filter_nextIterate tables matched by filter

Queries

ecs_query_newCreate a query
ecs_subquery_newCreate a subquery
ecs_query_freeCleanup a query
ecs_query_iterReturn a query iterator
ecs_query_iter_pageIterate over a query
ecs_query_nextProgress the query iterator
ecs_query_next_w_filterProgress the query iterator with filter
ecs_query_next_workerProgress the query iterator for a worker thread
ecs_query_order_bySort the output of a query
ecs_query_group_byGroup and sort matched tables
ecs_query_changedReturns whether the query data changed since the last iteration
ecs_query_orphanedReturns whether query is orphaned

Iterators

ecs_term_w_sizeObtain data for a query term

ecs_term(it,T,index)
((T*)ecs_term_w_size(it, sizeof(T), index))

Same as ecs_term_w_size, but accepts a type instead of a size.

ecs_term_idObtain the component/pair id for a term
ecs_term_sourceObtain the source for a term
ecs_term_sizeObtain the size for a term
ecs_term_is_readonlyTest whether the term is readonly This operation returns whether this is a readonly term
ecs_term_is_ownedTest whether the term is owned This operation returns whether the term is owned by the currently iterated entity
ecs_iter_typeGet the type of the currently entity/entities
ecs_iter_find_columnFind the column index for a given id
ecs_iter_column_w_sizeObtain data for a column index

ecs_iter_column(it,T,index)
((T*)ecs_iter_column_w_size(it, sizeof(T), index))

Same as ecs_iter_column_w_size, but accepts a type instead of a size.

ecs_iter_column_sizeObtain size for a column index

Staging

ecs_frame_beginBegin frame
ecs_frame_endEnd frame
ecs_staging_beginBegin staging
ecs_staging_endEnd staging
ecs_mergeMerge world or stage
ecs_defer_beginDefer operations until end of frame
ecs_defer_endEnd block of operations to defer
ecs_set_automergeEnable/disable automerging for world or stage
ecs_set_stagesConfigure world to have N stages
ecs_get_stage_countGet number of configured stages
ecs_get_stage_idGet current stage id
ecs_get_stageGet stage-specific world pointer
ecs_get_worldGet actual world from world.
ecs_stage_is_readonlyTest whether the current world object is readonly

Public table operations

ecs_table_from_strFind or create table with specified component string
ecs_table_from_typeFind or create table from type
ecs_table_get_typeGet type for table.
ecs_table_insertInsert record into table
ecs_table_countReturns the number of records in the table

Other Types

FLECS_NO_DEPRECATED_WARNINGS

FLECS_SYSTEM

Mentioned in:

FLECS_PIPELINE

FLECS_TIMER

Mentioned in:

FLECS_BULK

Mentioned in:

FLECS_DBG

Mentioned in:

FLECS_MODULE

Mentioned in:

FLECS_QUEUE

Mentioned in:

FLECS_READER_WRITER

Mentioned in:

FLECS_SNAPSHOT

Mentioned in:

FLECS_DIRECT_ACCESS

Mentioned in:

FLECS_STATS

Mentioned in:

FLECS_DEPRECATED

FLECS_FLOAT float