C API

API toggles & constants

ecs_float_t float

ecs_ftime_t ecs_float_t

FLECS_NO_DEPRECATED_WARNINGS

FLECS_LEGACY Define when building for C89 FLECS_NO_DEPRECATED_WARNINGS disables deprecated warnings

FLECS_DEBUG

FLECS_ACCURATE_COUNTERS Define to ensure that global counters used for statistics (such as the allocation counters in the OS API) are accurate in multithreaded applications, at the cost of increased overhead. Flecs debugging enables asserts. Used for input parameter checking and cheap sanity checks. There are lots of asserts in every part of the code, so this will slow down applications.

FLECS_CPP /* C++ API */

FLECS_SANITIZE Enables expensive checks that can detect issues early. Recommended for running tests or when debugging issues. This will severely slow down code. FLECS_SOFT_ASSERT Define to not abort for recoverable errors, like invalid parameters. An error is still thrown to the console. This is recommended for when running inside a third party runtime, such as the Unreal editor.

Note that internal sanity checks (ECS_INTERNAL_ERROR) will still abort a process, as this gives more information than a (likely) subsequent crash.

When a soft assert occurs, the code will attempt to minimize the number of side effects of the failed operation, but this may not always be possible. Even though an application may still be able to continue running after a soft assert, it should be treated as if in an undefined state. FLECS_KEEP_ASSERT By default asserts are disabled in release mode, when either FLECS_NDEBUG or NDEBUG is defined. Defining FLECS_KEEP_ASSERT ensures that asserts are not disabled. This define can be combined with FLECS_SOFT_ASSERT. Custom builds. The following macros let you customize with which addons Flecs is built. Without any addons Flecs is just a minimal ECS storage, but addons add features such as systems, scheduling and reflection. If an addon is disabled, it is excluded from the build, so that it consumes no resources. By default all addons are enabled.

You can customize a build by either whitelisting or blacklisting addons. To whitelist addons, first define the FLECS_CUSTOM_BUILD macro, which disables all addons. You can then manually select the addons you need by defining their macro, like "FLECS_SYSTEM".

To blacklist an addon, make sure to not define FLECS_CUSTOM_BUILD, and instead define the addons you don't need by defining FLECS_NO_<addon>, for example "FLECS_NO_SYSTEM". If there are any addons that depend on the blacklisted addon, an error will be thrown during the build.

Note that addons can have dependencies on each other. Addons will automatically enable their dependencies. To see the list of addons that was compiled in a build, enable tracing before creating the world by doing: ecs_log_set_level(0); which outputs the full list of addons Flecs was compiled with.

Mentioned in:

Readme / Addons

FLECS_MODULE /* Module support */

FLECS_PARSER /* String parser for queries */

FLECS_PLECS /* ECS data definition format */

Mentioned in:

FLECS_RULES /* Constraint solver for advanced queries */

FLECS_SNAPSHOT /* Snapshot & restore ECS data */

Mentioned in:

FLECS_STATS /* Access runtime statistics */

Mentioned in:

FLECS_MONITOR /* Track runtime statistics periodically */

Mentioned in:

FLECS_SYSTEM /* System support */

FLECS_PIPELINE /* Pipeline support */

FLECS_TIMER /* Timer support */

Mentioned in:

FLECS_META /* Reflection support */

FLECS_META_C /* Utilities for populating reflection data */

Mentioned in:

FLECS_UNITS /* Builtin standard units */

Mentioned in:

FLECS_EXPR /* Parsing strings to/from component values */

Mentioned in:

FLECS_JSON /* Parsing JSON to/from component values */

FLECS_DOC /* Document entities & components */

Mentioned in:

FLECS_COREDOC /* Documentation for core entities & components */

Mentioned in:

FLECS_LOG /* When enabled ECS provides more detailed logs */

Mentioned in:

FLECS_APP /* Application addon */

Mentioned in:

FLECS_OS_API_IMPL /* Default implementation for OS API */

FLECS_HTTP /* Tiny HTTP server for connecting to remote UI */

Mentioned in:

FLECS_REST /* REST API for querying application data */

Mentioned in:

Basic API types

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:

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.

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 optional id flags.

Mentioned in:

Quickstart / Pair

Manual / Local component handles

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Builder (C++)

Relationships Manual / Iterate all pairs for entity

Relationships Manual / Find all entities with a pair wildcard

Relationships Manual / Relationship wildcards

Relationships Manual / Inspecting relationships

typedef ecs_id_t ecs_entity_t

An entity identifier.

Mentioned in:

Readme / Show me the code!

Quickstart / Entity

Quickstart / Component

Quickstart / Tag

Quickstart / Pair

Quickstart / Hierarchies

Quickstart / Instancing

Quickstart / Type

Quickstart / System

Quickstart / Custom Pipeline

Quickstart / Observer

Manual / Naming conventions

Manual / Entity names

Manual / Macros

Manual / Entities

Manual / Generations

Manual / Basic usage

Manual / Advanced usage

Manual / Components

Manual / Global component handles

Manual / Component disabling

Manual / Tag handles

Manual / Modules

Manual / Hierarchies

Manual / Iteration

Manual / Path identifiers

Manual / Scoping

Manual / Paths and signatures

Manual / Inheritance

Manual / Overriding

Manual / Automatic overriding

Manual / Inheritance hierarchies

Manual / Prefabs

Manual / Deferred operations

Manual / Staging

Manual / Pipelines

Query Manual / Query Descriptor (C)

Query Manual / Wildcards

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Cached Queries

Relationships Manual / Introduction

Relationships Manual / Find first instance of a relationship for entity

Relationships Manual / Iterate all pairs for entity

Relationships Manual / Find all entities with a pair wildcard

Relationships Manual / Iterate all children for a parent

Relationships Manual / Relationship components

Relationships Manual / Using relationships to add components multiple times

Relationships Manual / Relationship wildcards

Relationships Manual / Inspecting relationships

Relationships Manual / The IsA relationship

Relationships Manual / Component sharing

Relationships Manual / The ChildOf relationship

Relationships Manual / Namespacing

Relationships Manual / Scoping

Relationships Manual / Examples

Relationships Manual / Tag property

Relationships Manual / Final property

Relationships Manual / DontInherit property

Relationships Manual / Transitive property

Relationships Manual / Exclusive property

Relationships Manual / Union property

Relationships Manual / Symmetric property

Relationships Manual / With property

Relationships Manual / OneOf property

Relationships Manual / Storing Relationships

typedef struct ecs_world_t ecs_world_t

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

Mentioned in:

Readme / Show me the code!

Quickstart / World

Quickstart / Module

Manual / Naming conventions

Manual / Components

Manual / Global component handles

Manual / Local component handles

Manual / Component disabling

Manual / Tagging

Manual / Tag handles

Manual / Modules

Query Manual / Query Descriptor (C)

REST API Manual / Explorer

typedef struct ecs_table_t ecs_table_t

A table is where entities and components are stored

Mentioned in:

Query Manual / Query Descriptor (C)

Relationships Manual / Inspecting relationships

typedef struct ecs_query_t ecs_query_t

A query allows for cached iteration over ECS data

Mentioned in:

Quickstart / Hierarchies

Quickstart / Query

Designing with Flecs / Use the right query

Manual / Hierarchical queries

Query Manual / Cached Queries

Query Manual / Query Descriptors (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Cached Queries

Relationships Manual / Introduction

Relationships Manual / Relationship wildcards

typedef struct ecs_rule_t ecs_rule_t

A rule implements a non-trivial filter

Mentioned in:

Query Manual / Rules

Query Manual / Query Descriptors (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

typedef struct ecs_observable_t ecs_observable_t

An observable contains lists of triggers for specific events/components

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.

Mentioned in:

Query Manual / Change Detection

typedef struct ecs_id_record_t ecs_id_record_t

typedef struct ecs_table_record_t ecs_table_record_t

typedef struct ecs_mixins_t ecs_mixins_t

ecs_type_tAn array with (component) ids

API constants

ECS_ID_CACHE_SIZE (32)

ECS_TERM_DESC_CACHE_SIZE (16)

ECS_OBSERVER_DESC_EVENT_COUNT_MAX (8)

ECS_VARIABLE_COUNT_MAX (64)

Function Prototypes

typedef void(* ecs_run_action_t)(ecs_iter_t *it)

Function prototype for runnables (systems, observers). The run callback overrides the default behavior for iterating through the results of a runnable object.

The default runnable iterates the iterator, and calls an iter_action (see below) for each returned result.

Parameters

it - The iterator to be iterated by the runnable.

typedef void(* ecs_iter_action_t)(ecs_iter_t *it)

Function prototype for iterables. A system may invoke a callback multiple times, typically once for each matched table.

Parameters

it - The iterator containing the data for the current match.

typedef void(* ecs_iter_init_action_t)(const ecs_world_t *world, const ecs_poly_t *iterable, ecs_iter_t *it, ecs_term_t *filter)

Function prototype for creating an iterator from a poly. Used to create iterators from poly objects with the iterable mixin. When a filter is provided, an array of two iterators must be passed to the function. This allows the mixin implementation to create a chained iterator when necessary, which requires two iterator objects.

Parameters

world - The world or stage for which to create the iterator.

iterable - An iterable poly object.

it - The iterator to create (out parameter)

filter - Optional term to filter results.

typedef bool(* ecs_iter_next_action_t)(ecs_iter_t *it)

Function prototype for iterating an iterator. Stored inside initialized iterators. This allows an application to * iterate an iterator without needing to know what created it.

Parameters

it - The iterator to iterate.

Returns
True if iterator has no more results, false if it does.

typedef void(* ecs_iter_fini_action_t)(ecs_iter_t *it)

Function prototype for freeing an iterator. Free iterator resources.

Parameters

it - The iterator to free.

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

Callback used for comparing components

typedef void(* ecs_sort_table_action_t)(ecs_world_t *world, ecs_table_t *table, ecs_entity_t *entities, void *ptr, int32_t size, int32_t lo, int32_t hi, ecs_order_by_action_t order_by)

Callback used for sorting the entire table of components

typedef uint64_t(* ecs_group_by_action_t)(ecs_world_t *world, ecs_table_t *table, ecs_id_t group_id, void *ctx)

Callback used for grouping tables in a query

typedef void *(* ecs_group_create_action_t)(ecs_world_t *world, uint64_t group_id, void *group_by_ctx)

typedef void(* ecs_group_delete_action_t)(ecs_world_t *world, uint64_t group_id, void *group_ctx, void *group_by_ctx)

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

typedef void(* ecs_ctx_free_t)(void *ctx)

Function to cleanup context data

typedef int(* ecs_compare_action_t)(const void *ptr1, const void *ptr2)

Callback used for sorting values

typedef uint64_t(* ecs_hash_value_action_t)(const void *ptr)

Callback used for hashing values

typedef void(* ecs_xtor_t)(void *ptr, int32_t count, const ecs_type_info_t *type_info)

Constructor/destructor callback

typedef void(* ecs_copy_t)(void *dst_ptr, const void *src_ptr, int32_t count, const ecs_type_info_t *type_info)

Copy is invoked when a component is copied into another component.

typedef void(* ecs_move_t)(void *dst_ptr, void *src_ptr, int32_t count, const ecs_type_info_t *type_info)

Move is invoked when a component is moved to another component.

typedef void(* ecs_poly_dtor_t)(ecs_poly_t *poly)

Public mixin types.

ecs_header_tHeader for ecs_poly_t objects.
ecs_iterable_tIterable mixin

Types used to describe queries.

ecs_inout_kind_tSpecify read/write access for term
ecs_oper_kind_tSpecify operator for term

EcsSelf (1u << 1) /* Match on self */

Term flags

Mentioned in:

Query Manual / Traversal Flags

Query Manual / Query Descriptor (C)

Query Manual / Query Descriptor (C)

EcsUp (1u << 2) /* Match by traversing upwards */

Mentioned in:

EcsDown (1u << 3) /* Match by traversing downwards (derived, cannot be set) */

Mentioned in:

EcsTraverseAll (1u << 4) /* Match all entities encountered through traversal */

EcsCascade (1u << 5) /* Sort results breadth first */

Mentioned in:

EcsParent (1u << 6) /* Short for up(ChildOf) */

Mentioned in:

EcsIsVariable (1u << 7) /* Term id is a variable */

Mentioned in:

EcsIsEntity (1u << 8) /* Term id is an entity */

EcsFilter (1u << 9) /* Prevent observer from triggering on term */

EcsTraverseFlags (EcsUp|EcsDown|EcsTraverseAll|EcsSelf|EcsCascade|EcsParent)

ecs_term_id_tType that describes a single identifier in a term
ecs_term_tType that describes a term (single element in a query)
ecs_filter_tFilters alllow for ad-hoc quick filtering of entity tables.
ecs_observer_tAn observer reacts to events matching multiple filter terms
ecs_type_hooks_tType that contains component lifecycle callbacks.
ecs_type_info_tType that contains component information (passed to ctors/dtors/...)

Types used for creating API constructs

ecs_entity_desc_tUsed with ecs_entity_init
ecs_bulk_desc_tUsed with ecs_bulk_init
ecs_component_desc_tUsed with ecs_component_init.
ecs_filter_desc_tUsed with ecs_filter_init.
ecs_query_desc_tUsed with ecs_query_init.
ecs_observer_desc_tUsed with ecs_observer_init.

Builtin components

EcsIdentifierA (string) identifier
EcsComponentComponent information.
EcsPolyComponent for storing a poly object

typedef ecs_iterable_t EcsIterable

Component for iterable entities

Miscalleneous types

ecs_value_t
ecs_world_info_tType that contains information about the world.
ecs_query_group_info_tType that contains information about a query group.

Id Flags

ECS_ID_FLAG_BIT (1ull << 63)

Bit added to flags to differentiate between id flags and generation

Builtin components & tags

ecs_id overloadBuiltin component ids
ecs_id overloadPipeline module component ids
ecs_id overloadTimer module component ids

EcsLastInternalComponentId (ecs_id(EcsPoly))

EcsFirstUserComponentId (32)

EcsFirstUserEntityId (ECS_HI_COMPONENT_ID + 128)

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_is_finiReturns whether the world is being deleted.
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_hooks_idRegister hooks for component
ecs_get_hooks_idGet hooks for component.
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_set_entity_generationSets the entity's generation in the world's sparse set
ecs_enable_range_checkEnable/disable range limits
ecs_measure_frame_timeMeasure frame time
ecs_measure_system_timeMeasure system time
ecs_set_target_fpsSet target frames per second (FPS) for application
ecs_run_aperiodicForce aperiodic actions
ecs_delete_empty_tablesCleanup empty tables
ecs_get_worldGet world from poly.
ecs_get_entityGet entity from poly.
_ecs_poly_isTest if pointer is of specified type

ecs_poly_is(object,type)
_ecs_poly_is(object, type##_magic)

Creating Entities

ecs_new_idCreate new entity id
ecs_new_low_idCreate new low id
ecs_new_w_idCreate new entity
ecs_entity_initFind or create an entity
ecs_bulk_initBulk create/populate new entities
ecs_component_initFind or create a component
ecs_bulk_new_w_idCreate N new entities
ecs_cloneClone an entity This operation clones the components of one entity into another entity

Adding & Removing

ecs_add_idAdd a (component) id to an entity
ecs_remove_idRemove a (component) id from an entity
ecs_override_idAdd override for (component) id

Enabling & Disabling components.

ecs_enable_idEnable or disable component
ecs_is_enabled_idTest if component is enabled

Pairs

ecs_make_pairMake a pair id

Deleting Entities and components

ecs_clearClear all components
ecs_deleteDelete an entity
ecs_delete_withDelete all entities with the specified id
ecs_remove_allRemove all instances of the specified id

Getting Components

ecs_get_idGet an immutable pointer to a component
ecs_ref_init_idCreate a component ref
ecs_ref_get_idGet component from ref
ecs_ref_updateUpdate ref

Setting Components

ecs_get_mut_idGet a mutable pointer to a component
ecs_write_beginBegin exclusive write access to entity
ecs_write_endEnd exclusive write access to entity
ecs_read_beginBegin read access to entity
ecs_read_endEnd read access to entity
ecs_record_get_idGet component from entity record
ecs_record_get_mut_idSame as ecs_record_get_id, but returns a mutable pointer
ecs_emplace_idEmplace a component
ecs_modified_idSignal that a component has been modified
ecs_set_idSet the value of a component

Entity Metadata

ecs_is_validTest whether an entity is valid
ecs_is_aliveTest whether an entity is alive
ecs_strip_generationRemove generation from entity id.
ecs_get_aliveGet alive identifier
ecs_ensureEnsure id is alive
ecs_ensure_idSame as ecs_ensure, but for (component) ids
ecs_existsTest whether an entity exists
ecs_get_typeGet the type of an entity.
ecs_get_tableGet the table of an entity.
ecs_get_storage_tableGet the storage table of an entity
ecs_get_type_infoGet the type for an id
ecs_get_typeidGet the type for an id
ecs_id_is_tagReturns whether specified id a tag
ecs_id_in_useReturns whether specified id is in use
ecs_get_nameGet the name of an entity
ecs_get_symbolGet the symbol of an entity
ecs_set_nameSet the name of an entity
ecs_set_symbolSet the symbol of an entity
ecs_set_aliasSet alias for entity
ecs_id_flag_strConvert id flag to string
ecs_id_strConvert id to string
ecs_id_str_bufWrite id string to buffer
ecs_type_strConvert type to string
ecs_table_strConvert table to string
ecs_entity_strConvert entity to string
ecs_has_idTest if an entity has an entity
ecs_get_targetGet the target of a relationship
ecs_get_target_for_idGet the target of a relationship for a given id
ecs_enableEnable or disable an entity
ecs_count_idCount entities that have the specified id

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_symbolLookup an entity by its symbol name

Paths

ecs_get_path_w_sepGet a path identifier for an entity
ecs_get_path_w_sep_bufWrite path identifier to buffer
ecs_new_from_path_w_sepFind or create entity from path
ecs_add_path_w_sepAdd specified path to entity

Scopes

ecs_set_scopeSet the current scope
ecs_get_scopeGet the current scope
ecs_set_withSet current with id
ecs_get_withGet current with id
ecs_set_name_prefixSet a name prefix for newly created entities
ecs_set_lookup_pathSet search path for lookup operations
ecs_get_lookup_pathGet current lookup path

Terms

ecs_term_iterIterator for a single (component) id
ecs_term_chain_iterReturn a chained term iterator
ecs_term_nextProgress a term iterator
ecs_childrenIterator for a parent's children
ecs_children_nextProgress a children iterator
ecs_term_id_is_setTest whether term id is set.
ecs_term_is_initializedTest whether a term is set
ecs_term_match_this
ecs_term_match_0
ecs_term_finalizeFinalize term
ecs_term_copyCopy resources of a term to another term
ecs_term_moveMove resources of a term to another term
ecs_term_finiFree resources of term
ecs_id_matchUtility to match an id with a pattern
ecs_id_is_pairUtility to check if id is a pair.
ecs_id_is_wildcardUtility to check if id is a wildcard.
ecs_id_is_validUtility to check if id is valid
ecs_id_get_flagsGet flags associated with id

Filters

ecs_filter_initInitialize filter A filter is a lightweight object that can be used to query for entities in a world
ecs_filter_finiDeinitialize filter
ecs_filter_finalizeFinalize filter
ecs_filter_find_this_varFind index for This variable
ecs_term_strConvert ter, to string expression
ecs_filter_strConvert filter to string expression
ecs_filter_iterReturn a filter iterator
ecs_filter_chain_iterReturn a chained filter iterator
ecs_filter_pivot_termGet pivot term for filter
ecs_filter_nextIterate tables matched by filter
ecs_filter_next_instancedSame as ecs_filter_next, but always instanced
ecs_filter_moveMove resources of one filter to another.
ecs_filter_copyCopy resources of one filter to another.

Queries

ecs_query_initCreate a query
ecs_query_finiDestroy a query
ecs_query_get_filterGet filter from a query
ecs_query_iterReturn a query iterator
ecs_query_nextProgress the query iterator
ecs_query_next_instancedSame as ecs_query_next, but always instanced
ecs_query_next_tableFast alternative to ecs_query_next that only returns matched tables
ecs_query_populatePopulate iterator fields
ecs_query_changedReturns whether the query data changed since the last iteration
ecs_query_skipSkip a table while iterating
ecs_query_set_groupSet group to iterate for query iterator
ecs_query_get_group_ctxGet context of query group
ecs_query_get_group_infoGet information about query group
ecs_query_orphanedReturns whether query is orphaned
ecs_query_strConvert query to string.
ecs_query_table_countReturns number of tables query matched with.
ecs_query_empty_table_countReturns number of empty tables query matched with.
ecs_query_entity_countReturns number of entities query matched with

Iterators

ecs_iter_polyCreate iterator from poly object
ecs_iter_nextProgress any iterator
ecs_iter_finiCleanup iterator resources
ecs_iter_countCount number of matched entities in query
ecs_iter_is_trueTest if iterator is true
ecs_iter_firstGet first matching entity from iterator
ecs_iter_set_varSet value for iterator variable
ecs_iter_set_var_as_tableSame as ecs_iter_set_var, but for a table
ecs_iter_set_var_as_rangeSame as ecs_iter_set_var, but for a range of entities This constrains the variable to a range of entities in a table.
ecs_iter_get_varGet value of iterator variable as entity
ecs_iter_get_var_as_tableGet value of iterator variable as table
ecs_iter_get_var_as_rangeGet value of iterator variable as table range
ecs_iter_var_is_constrainedReturns whether variable is constrained
ecs_page_iterCreate a paged iterator
ecs_page_nextProgress a paged iterator
ecs_worker_iterCreate a worker iterator
ecs_worker_nextProgress a worker iterator
ecs_field_w_sizeObtain data for a query field
ecs_field_is_readonlyTest whether the field is readonly
ecs_field_is_writeonlyTest whether the field is writeonly
ecs_field_is_setTest whether field is set.
ecs_field_idReturn id matched for field.
ecs_field_srcReturn field source
ecs_field_sizeReturn field type size
ecs_field_is_selfTest whether the field is matched on self
ecs_iter_strConvert iterator to string
ecs_iter_find_columnFind the column index for a given id
ecs_iter_column_w_sizeObtain data for a column index
ecs_iter_column_sizeObtain size for a column index

Staging

ecs_frame_beginBegin frame
ecs_frame_endEnd frame
ecs_readonly_beginBegin readonly mode
ecs_readonly_endEnd readonly mode
ecs_mergeMerge world or stage
ecs_defer_beginDefer operations until end of frame
ecs_is_deferredTest if deferring is enabled for current stage.
ecs_defer_endEnd block of operations to defer
ecs_defer_suspendSuspend deferring but do not flush queue
ecs_defer_resumeResume deferring
ecs_set_automergeEnable/disable automerging for world or stage
ecs_set_stage_countConfigure 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_stage_is_readonlyTest whether the current world is readonly
ecs_async_stage_newCreate asynchronous stage
ecs_async_stage_freeFree asynchronous stage
ecs_stage_is_asyncTest whether provided stage is asynchronous.

Search functions for component ids.

Low-level functions to search for component ids in table types.

ecs_search_offsetSearch for component id in table type starting from an offset
ecs_search_relationSearch for component/relationship id in table type starting from an offset

Public table operations

Low-level table functions. These functions are intended to enable the creation of higher-level operations. It is not recommended to use these operations directly in application code as they do not provide the same safety guarantees as the other APIs.

ecs_table_get_typeGet type for table.
ecs_table_get_columnGet column from table
ecs_table_get_indexGet column index for id
ecs_table_get_storage_tableGet storage type for table.
ecs_table_type_to_storage_indexConvert index in table type to index in table storage type.
ecs_table_storage_to_type_indexConvert index in table storage type to index in table type.
ecs_table_countReturns the number of records in the table
ecs_table_add_idGet table that has all components of current table plus the specified id
ecs_table_remove_idGet table that has all components of current table minus the specified id
ecs_table_lockLock or unlock table
ecs_table_unlockUnlock a table
ecs_table_has_moduleReturns whether table is a module or contains module contents Returns true for tables that have module contents
ecs_table_swap_rowsSwaps two elements inside the table
ecs_commitCommit (move) entity to a table
ecs_record_findFind record for entity.
ecs_record_get_columnGet component pointer from column/record.

API for dynamic values.

Construct, destruct, copy and move dynamically created values.

ecs_value_initConstruct a value in existing storage
ecs_value_init_w_type_infoConstruct a value in existing storage
ecs_value_newConstruct a value in new storage
ecs_value_fini_w_type_infoDestruct a value
ecs_value_finiDestruct a value
ecs_value_freeDestruct a value, free storage
ecs_value_copy_w_type_infoCopy value.
ecs_value_copyCopy value.
ecs_value_move_w_type_infoMove value.
ecs_value_moveMove value.
ecs_value_move_ctor_w_type_infoMove construct value.
ecs_value_move_ctorMove construct value.

ecs_value(T,ptr)
((ecs_value_t){ecs_id(T), ptr})

ecs_value_new_t(world,T)
ecs_value_new(world, ecs_id(T))

Macros that help with creation of ECS objects.

ECS_DECLARE(id)
ecs_entity_t id, ecs_id(id)

ECS_ENTITY_DEFINE(world,id_,...)
{
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, NULL);
}
(void)id_;
(void)ecs_id(id_);

ECS_ENTITY(world,id,...)
ecs_entity_t ecs_id(id);
ecs_entity_t id = 0;
ECS_ENTITY_DEFINE(world, id, __VA_ARGS__);

Mentioned in:

ECS_TAG_DEFINE(world,id)
ECS_ENTITY_DEFINE(world, id, 0)

Mentioned in:

ECS_TAG(world,id)
ECS_ENTITY(world, id, 0)

Mentioned in:

ECS_PREFAB_DEFINE(world,id,...)
ECS_ENTITY_DEFINE(world, id, Prefab, __VA_ARGS__)

ECS_PREFAB(world,id,...)
ECS_ENTITY(world, id, Prefab, __VA_ARGS__)

Mentioned in:

ECS_COMPONENT_DECLARE(id)
ecs_entity_t ecs_id(id)

Mentioned in:

ECS_COMPONENT_DEFINE(world,id_)
{
ecs_component_desc_t desc = {0};
ecs_entity_desc_t edesc = {0};
edesc.id = ecs_id(id_);
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, NULL);
}

Mentioned in:

ECS_COMPONENT(world,id)
ecs_entity_t ecs_id(id) = 0;
ECS_COMPONENT_DEFINE(world, id);
(void)ecs_id(id)

Mentioned in:

ECS_SYSTEM_DECLARE(id)
ecs_entity_t ecs_id(id)

Mentioned in:

ECS_OBSERVER_DEFINE(world,id_,kind,...)
{
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.filter.expr = #__VA_ARGS__;
desc.events[0] = kind;
ecs_id(id_) = ecs_observer_init(world, &desc);
ecs_assert(ecs_id(id_) != 0, ECS_INVALID_PARAMETER, NULL);
}

ECS_OBSERVER(world,id,kind,...)
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;

Mentioned in:

Convenience macros for using init functions with less code

ecs_entity(world,...)
ecs_entity_init(world, &(ecs_entity_desc_t) __VA_ARGS__ )

Mentioned in:

ecs_filter(world,...)
ecs_filter_init(world, &(ecs_filter_desc_t) __VA_ARGS__ )

Mentioned in:

ecs_query(world,...)
ecs_query_init(world, &(ecs_query_desc_t) __VA_ARGS__ )

Mentioned in:

ecs_observer(world,...)
ecs_observer_init(world, &(ecs_observer_desc_t) __VA_ARGS__ )

Convenience macros that help with component comparison and sorting

ecs_sort_table(id)
ecs_id(id##_sort_table)

ecs_compare(id)
ecs_id(id##_compare_fn)

ECS_SORT_TABLE_WITH_COMPARE(id,op_name,compare_fn,...)

ECS_SORT_TABLE(id,...)
ECS_SORT_TABLE_WITH_COMPARE(id, ecs_sort_table(id), ecs_compare(id), __VA_ARGS__)

ECS_COMPARE(id,...)
int ecs_compare(id)(ecs_entity_t e1, const void* ptr1, ecs_entity_t e2, const void* ptr2) {
__VA_ARGS__
}

Convenience macros that wrap ECS operations

ecs_set_hooks(world,T,...)
ecs_set_hooks_id(world, ecs_id(T), &(ecs_type_hooks_t)__VA_ARGS__)

ecs_get_hooks(world,T)
ecs_get_hooks_id(world, ecs_id(T));

ecs_new(world,T)
ecs_new_w_id(world, ecs_id(T))

Mentioned in:

ecs_new_w_pair(world,first,second)
ecs_new_w_id(world, ecs_pair(first, second))

Mentioned in:

ecs_bulk_new(world,component,count)
ecs_bulk_new_w_id(world, ecs_id(component), count)

ecs_new_entity(world,n)
ecs_entity_init(world, &(ecs_entity_desc_t){
.name = n,
})

Mentioned in:

ecs_new_prefab(world,n)
ecs_entity_init(world, &(ecs_entity_desc_t){
.name = n,
.add = {EcsPrefab}
})

ecs_add(world,entity,T)
ecs_add_id(world, entity, ecs_id(T))

Mentioned in:

ecs_add_pair(world,subject,first,second)
ecs_add_id(world, subject, ecs_pair(first, second))

Mentioned in:

ecs_remove(world,entity,T)
ecs_remove_id(world, entity, ecs_id(T))

Mentioned in:

ecs_remove_pair(world,subject,first,second)
ecs_remove_id(world, subject, ecs_pair(first, second))

Mentioned in:

ecs_override(world,entity,T)
ecs_override_id(world, entity, ecs_id(T))

ecs_override_pair(world,subject,first,second)
ecs_override_id(world, subject, ecs_pair(first, second))

ecs_delete_children(world,parent)
ecs_delete_with(world, ecs_pair(EcsChildOf, parent))

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

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

Mentioned in:

ecs_set_pair(world,subject,First,second,...)
ecs_set_id(world, subject,
ecs_pair(ecs_id(First), second),
sizeof(First), &(First)__VA_ARGS__)

Mentioned in:

ecs_set_pair_second(world,subject,first,Second,...)
ecs_set_id(world, subject,
ecs_pair(first, ecs_id(Second)),
sizeof(Second), &(Second)__VA_ARGS__)

Mentioned in:

ecs_set_pair_object ecs_set_pair_second

ecs_set_override(world,entity,T,...)
ecs_add_id(world, entity, ECS_OVERRIDE | ecs_id(T));
ecs_set(world, entity, T, __VA_ARGS__)

ecs_emplace(world,entity,T)
(ECS_CAST(T*, ecs_emplace_id(world, entity, ecs_id(T))))

ecs_get(world,entity,T)
(ECS_CAST(const T*, ecs_get_id(world, entity, ecs_id(T))))

Mentioned in:

ecs_get_pair(world,subject,First,second)
(ECS_CAST(const First*, ecs_get_id(world, subject,
ecs_pair(ecs_id(First), second))))

Mentioned in:

ecs_get_pair_second(world,subject,first,Second)
(ECS_CAST(const Second*, ecs_get_id(world, subject,
ecs_pair(first, ecs_id(Second)))))

ecs_get_pair_object ecs_get_pair_second

Mentioned in:

ecs_record_get(world,record,T)
(ECS_CAST(const T*, ecs_record_get_id(world, record, ecs_id(T))))

ecs_record_get_pair(world,record,First,second)
(ECS_CAST(const First*, ecs_record_get_id(world, record,
ecs_pair(ecs_id(First), second))))

ecs_record_get_pair_second(world,record,first,Second)
(ECS_CAST(const Second*, ecs_record_get_id(world, record,
ecs_pair(first, ecs_id(Second)))))

ecs_record_get_mut(world,record,T)
(ECS_CAST(T*, ecs_record_get_mut_id(world, record, ecs_id(T))))

ecs_record_get_mut_pair(world,record,First,second)
(ECS_CAST(First*, ecs_record_get_mut_id(world, record,
ecs_pair(ecs_id(First), second))))

ecs_record_get_mut_pair_second(world,record,first,Second)
(ECS_CAST(Second*, ecs_record_get_mut_id(world, record,
ecs_pair(first, ecs_id(Second)))))

ecs_record_get_mut_pair_object ecs_record_get_mut_pair_second

ecs_ref_init(world,entity,T)
ecs_ref_init_id(world, entity, ecs_id(T))

ecs_ref_get(world,ref,T)
(ECS_CAST(const T*, ecs_ref_get_id(world, ref, ecs_id(T))))

ecs_get_mut(world,entity,T)
(ECS_CAST(T*, ecs_get_mut_id(world, entity, ecs_id(T))))

Mentioned in:

ecs_get_mut_pair(world,subject,First,second)
(ECS_CAST(First*, ecs_get_mut_id(world, subject,
ecs_pair(ecs_id(First), second))))

ecs_get_mut_pair_second(world,subject,first,Second)
(ECS_CAST(Second*, ecs_get_mut_id(world, subject,
ecs_pair(first, ecs_id(Second)))))

ecs_get_mut_pair_object ecs_get_mut_pair_second

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

Mentioned in:

ecs_modified_pair(world,subject,first,second)
ecs_modified_id(world, subject, ecs_pair(first, second))

ecs_singleton_add(world,comp)
ecs_add(world, ecs_id(comp), comp)

ecs_singleton_remove(world,comp)
ecs_remove(world, ecs_id(comp), comp)

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

Mentioned in:

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)

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

ecs_has(world,entity,T)
ecs_has_id(world, entity, ecs_id(T))

Mentioned in:

ecs_has_pair(world,entity,first,second)
ecs_has_id(world, entity, ecs_pair(first, second))

Mentioned in:

ecs_owns_id(world,entity,id)
(ecs_search(world, ecs_get_table(world, entity), id, 0) != -1)

ecs_owns_pair(world,entity,first,second)
ecs_owns_id(world, entity, ecs_pair(first, second))

ecs_owns(world,entity,T)
ecs_owns_id(world, entity, ecs_id(T))

ecs_shares_id(world,entity,id)
(ecs_search_relation(world, ecs_get_table(world, entity), 0, ecs_id(id),
EcsIsA, 1, 0, 0, 0, 0) != -1)

ecs_shares_pair(world,entity,first,second)
(ecs_shares_id(world, entity, ecs_pair(first, second)))

ecs_shares(world,entity,T)
(ecs_shares_id(world, entity, ecs_id(T)))

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

Mentioned in:

ecs_is_enabled_component(world,entity,T)
ecs_is_enabled_id(world, entity, ecs_id(T))

Mentioned in:

ecs_enable_pair(world,entity,First,second,enable)
ecs_enable_id(world, entity, ecs_pair(ecs_id(First), second), enable)

ecs_is_enabled_pair(world,entity,First,second)
ecs_is_enabled_id(world, entity, ecs_pair(ecs_id(First), second))

ecs_count(world,type)
ecs_count_id(world, ecs_id(type))

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

Mentioned in:

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

Mentioned in:

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

Mentioned in:

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

Mentioned in:

ecs_get_fullpath_buf(world,child,buf)
ecs_get_path_w_sep_buf(world, 0, child, ".", NULL, buf)

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

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

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

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

ecs_field(it,T,index)
(ECS_CAST(T*, ecs_field_w_size(it, sizeof(T), index)))

Mentioned in:

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

Utility macros for commonly used operations

ecs_isa(e)
ecs_pair(EcsIsA, e)

Mentioned in:

ecs_childof(e)
ecs_pair(EcsChildOf, e)

Mentioned in:

ecs_dependson(e)
ecs_pair(EcsDependsOn, e)

Mentioned in:

Temp macros for easing the transition to v3

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

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

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

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

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); });

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; });

ECS_ON_ADD(type,ptr,...)
ECS_HOOK_IMPL(type, ecs_on_add(type), ptr, __VA_ARGS__)

Declare component hooks Example: ECS_ON_SET(MyType, ptr, { printf("%d
n", ptr->value); });

ECS_ON_REMOVE(type,ptr,...)
ECS_HOOK_IMPL(type, ecs_on_remove(type), ptr, __VA_ARGS__)

ECS_ON_SET(type,ptr,...)
ECS_HOOK_IMPL(type, ecs_on_set(type), ptr, __VA_ARGS__)

ecs_ctor(type)
type##_ctor

ecs_dtor(type)
type##_dtor

ecs_copy(type)
type##_copy

ecs_move(type)
type##_move

ecs_on_set(type)
type##_on_set

ecs_on_add(type)
type##_on_add

ecs_on_remove(type)
type##_on_remove

ecs_query_new(world,q_expr)
ecs_query_init(world, &(ecs_query_desc_t){
.filter.expr = q_expr
})

Mentioned in:

ecs_rule_new(world,q_expr)
ecs_rule_init(world, &(ecs_filter_desc_t){
.expr = q_expr
})

Other Types

FLECS_API ecs_filter_t ECS_FILTER_INIT

Use this variable to initialize user-allocated filter object

Mentioned in:

Query Manual / Filter

FLECS_API const ecs_id_t ECS_PAIR

Indicates that the id is a pair.

FLECS_API const ecs_id_t ECS_OVERRIDE

Automatically override component when its inherited

Mentioned in:

Manual / Automatic overriding

FLECS_API const ecs_id_t ECS_TOGGLE

Adds bitset to storage which allows component to be enabled/disabled

FLECS_API const ecs_id_t ECS_AND

Include all components from entity to which AND is applied

FLECS_API const ecs_entity_t EcsQuery

FLECS_API const ecs_entity_t EcsObserver

FLECS_API const ecs_entity_t EcsSystem

Mentioned in:

FLECS_API const ecs_entity_t EcsFlecs

Root scope for builtin flecs entities

FLECS_API const ecs_entity_t EcsFlecsCore

FLECS_API const ecs_entity_t EcsWorld

Mentioned in:

FLECS_API const ecs_entity_t EcsWildcard

Mentioned in:

FLECS_API const ecs_entity_t EcsAny

Mentioned in:

FLECS_API const ecs_entity_t EcsThis

FLECS_API const ecs_entity_t EcsVariable

FLECS_API const ecs_entity_t EcsTransitive

Mentioned in:

FLECS_API const ecs_entity_t EcsReflexive

FLECS_API const ecs_entity_t EcsFinal

Ensures that entity/component cannot be used as target in IsA relationship. Final can improve the performance of rule-based queries, as they will not attempt to substitute a final component with its subsets.

Behavior: if IsA(X, Y) and Final(Y) throw error

Mentioned in:

Relationships Manual / Final property

FLECS_API const ecs_entity_t EcsDontInherit

Ensures that component is never inherited from an IsA target.

Behavior: if DontInherit(X) and X(B) and IsA(A, B) then X(A) is false.

Mentioned in:

Relationships Manual / DontInherit property

FLECS_API const ecs_entity_t EcsSymmetric

Mentioned in:

FLECS_API const ecs_entity_t EcsExclusive

Mentioned in:

FLECS_API const ecs_entity_t EcsAcyclic

FLECS_API const ecs_entity_t EcsWith

Mentioned in:

FLECS_API const ecs_entity_t EcsOneOf

Mentioned in:

FLECS_API const ecs_entity_t EcsTag

Mentioned in:

FLECS_API const ecs_entity_t EcsUnion

Mentioned in:

FLECS_API const ecs_entity_t EcsName

Mentioned in:

FLECS_API const ecs_entity_t EcsSymbol

FLECS_API const ecs_entity_t EcsAlias

FLECS_API const ecs_entity_t EcsChildOf

Mentioned in:

FLECS_API const ecs_entity_t EcsIsA

Mentioned in:

FLECS_API const ecs_entity_t EcsDependsOn

Mentioned in:

FLECS_API const ecs_entity_t EcsSlotOf

FLECS_API const ecs_entity_t EcsModule

Mentioned in:

FLECS_API const ecs_entity_t EcsPrivate

Mentioned in:

FLECS_API const ecs_entity_t EcsPrefab

Mentioned in:

FLECS_API const ecs_entity_t EcsDisabled

FLECS_API const ecs_entity_t EcsOnAdd

Mentioned in:

FLECS_API const ecs_entity_t EcsOnRemove

FLECS_API const ecs_entity_t EcsOnSet

Mentioned in:

FLECS_API const ecs_entity_t EcsUnSet

FLECS_API const ecs_entity_t EcsMonitor

FLECS_API const ecs_entity_t EcsOnDelete

Mentioned in:

FLECS_API const ecs_entity_t EcsOnTableEmpty

FLECS_API const ecs_entity_t EcsOnTableFill

FLECS_API const ecs_entity_t EcsOnDeleteTarget

Mentioned in:

FLECS_API const ecs_entity_t EcsRemove

Mentioned in:

FLECS_API const ecs_entity_t EcsDelete

Mentioned in:

FLECS_API const ecs_entity_t EcsPanic

FLECS_API const ecs_entity_t EcsDefaultChildComponent

FLECS_API const ecs_entity_t EcsEmpty

FLECS_API const ecs_entity_t EcsPreFrame

FLECS_API const ecs_entity_t EcsOnLoad

Mentioned in:

FLECS_API const ecs_entity_t EcsPostLoad

Mentioned in:

FLECS_API const ecs_entity_t EcsPreUpdate

Mentioned in:

FLECS_API const ecs_entity_t EcsOnUpdate

Mentioned in:

FLECS_API const ecs_entity_t EcsOnValidate

Mentioned in:

FLECS_API const ecs_entity_t EcsPostUpdate

Mentioned in:

FLECS_API const ecs_entity_t EcsPreStore

Mentioned in:

FLECS_API const ecs_entity_t EcsOnStore

Mentioned in:

FLECS_API const ecs_entity_t EcsPostFrame

FLECS_API const ecs_entity_t EcsPhase

Mentioned in:

ecs_event_desc_t
ecs_emitSend event
ecs_emit_2
ecs_observer_initCreate observer
ecs_observer_default_run_actionDefault run action for observer
ecs_get_observer_ctx
ecs_get_observer_binding_ctx