A type is a list of (component) ids.
Types are used to communicate the “type” of an entity. In most type systems a
typeof operation returns a single type. In ECS however, an entity can have
multiple components, which is why an ECS type consists of a vector of ids.
Helper type to describe translation between two units. Note that this
is not intended as a generic approach to unit conversions (e.g. from celsius
to fahrenheit) but to translate between units that derive from the same base
(e.g. meters to kilometers).
Used like (EcsDefaultChildComponent, Component). When added to an entity,
this informs serialization formats which component to use when a value is
assigned to an entity without specifying the component. This is intended as
a hint, serialization formats are not required to use it. Adding this
component does not change the behavior of core ECS operations.
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.
Tag to indicate that relationship is stored as union. Union relationships
enable changing the target of a union without switching tables. Union
relationships are also marked as exclusive.
Add a (component) id to an entity.
This operation adds a single (component) id to an entity. If the entity
already has the id, this operation will have no side effects.
Create a new alert.
An alert is a query that is evaluated periodically and creates alert
instances for each entity that matches the query. Alerts can be used to
automate detection of errors in an application.
Run application.
This will run the application with the parameters specified in desc. After
the application quits (ecs_quit is called) the world will be cleaned up.
Default frame callback.
This operation will run a single frame. By default this operation will invoke
ecs_progress directly, unless a custom frame action is set.
Serialize array into JSON string.
This operation serializes a value of the provided type to a JSON string. The
memory pointed to must be large enough to contain a value of the used type.
Create asynchronous stage.
An asynchronous stage can be used to asynchronously queue operations for
later merging with the world. An asynchronous stage is similar to a regular
stage, except that it does not allow reading from the world.
Clone an entity
This operation clones the components of one entity into another entity. If
no destination entity is provided, a new entity will be created. Component
values are not copied unless copy_value is true.
Find or create a component.
This operation creates a new component, or finds an existing one. The find or
create behavior is the same as ecs_entity_init.
Defer operations until end of frame.
When this operation is invoked while iterating, operations inbetween the
defer_begin and defer_end operations are executed at the end of the frame.
Delete an entity.
This operation will delete an entity and all of its components. The entity id
will be made available for recycling. If the entity passed to ecs_delete is
not alive, the operation will have no side effects.
Cleanup empty tables.
This operation cleans up empty tables that meet certain conditions. Having
large amounts of empty tables does not negatively impact performance of the
ECS, but can take up considerable amounts of memory, especially in
applications with many components, and many components per entity.
Dimension the world for a specified number of entities.
This operation will preallocate memory in the world for the specified number
of entities. Specifying a number lower than the current number of entities in
the world will have no effect.
Add human-readable name to entity.
Contrary to entity names, human readable names do not have to be unique and
can contain special characters used in the query language like ‘*’.
Emplace a component.
Emplace is similar to get_mut except that the component constructor is not
invoked for the returned pointer, allowing the component to be “constructed”
directly in the storage.
Enable or disable entity.
This operation enables or disables an entity by adding or removing the
EcsDisabled tag. A disabled entity will not be matched with any systems,
unless the system explicitly specifies the EcsDisabled tag.
Enable or disable component.
Enabling or disabling a component does not add or remove a component from an
entity, but prevents it from being matched with queries. This operation can
be useful when a component must be temporarily disabled without destroying
its value. It is also a more performant operation for when an application
needs to add/remove components at high frequency, as enabling/disabling is
cheaper than a regular add or remove.
Enable/disable range limits.
When an application is both a receiver of range-limited entities and a
producer of range-limited entities, range checking needs to be temporarily
disabled when inserting received entities. Range checking is disabled on a
stage, so setting this value is thread safe.
Ensure id is alive.
This operation ensures that the provided id is alive. This is useful in
scenarios where an application has an existing id that has not been created
with ecs_new (such as a global constant or an id from a remote application).
Same as ecs_ensure, but for (component) ids.
An id can be an entity or pair, and can contain id flags. This operation
ensures that the entity (or entities, for a pair) are alive.
Parse JSON object with multiple component values into entity. The format
is the same as the one outputted by ecs_entity_to_json, but at the moment
only supports the “ids” and “values” member.
Find or create an entity.
This operation creates a new entity, or modifies an existing one. When a name
is set in the ecs_entity_desc_t::name field and ecs_entity_desc_t::entity is
not set, the operation will first attempt to find an existing entity by that
name. If no entity with that name can be found, it will be created.
Serialize entity into JSON string.
This creates a JSON object with the entity’s (path) name, which components
and tags the entity has, and the component values.
Return index of matched table column.
This function only returns column indices for fields that have been matched
on the $this variable. Fields matched on other tables will return -1.
Test whether the field is readonly.
This operation returns whether the field is readonly. Readonly fields are
annotated with [in], or are added as a const type in the C++ API.
Test whether the field is matched on self.
This operation returns whether the field is matched on the currently iterated
entity. This function will return false when the field is owned by another
entity, such as a parent or a prefab.
Obtain data for a query field.
This operation retrieves a pointer to an array of data that belongs to the
term in the query. The index refers to the location of the term in the query,
and starts counting from one.
Return a chained filter iterator.
A chained iterator applies a filter to the results of the input iterator. The
resulting iterator must be iterated with ecs_filter_next.
Finalize filter.
When manually assigning an array of terms to the filter struct (so not when
using ecs_filter_init), this operation should be used to ensure that all
terms are assigned properly and all (derived) fields have been set.
Find index for $this variable.
This operation looks up the index of the $this variable. This index can
be used in operations like ecs_iter_set_var and ecs_iter_get_var.
Initialize filter
A filter is a lightweight object that can be used to query for entities in
a world. Filters, as opposed to queries, do not cache results. They are
therefore slower to iterate, but are faster to create.
Iterate tables matched by filter.
This operation progresses the filter iterator to the next table. The
iterator must have been initialized with ecs_filter_iter. This operation
must be invoked at least once before interpreting the contents of the
iterator.
Recursively flatten relationship for target entity (experimental).
This operation combines entities in the subtree of the specified pair from
different parents in the same table. This can reduce memory fragmentation
and reduces the number of tables in the storage, which improves RAM
utilization and various other operations, such as entity cleanup.
Begin frame.
When an application does not use ecs_progress to control the main loop, it
can still use Flecs features such as FPS limiting and time measurements. This
operation needs to be invoked whenever a new frame is about to get processed.
Return alert instance for specified alert.
This operation returns the alert instance for the specified alert. If the
alert is not active for the entity, the operation will return 0.
Return number of active alerts for entity.
When a valid alert entity is specified for the alert parameter, the operation
will return whether the specified alert is active for the entity. When no
alert is specified, the operation will return the total number of active
alerts for the entity.
Get alive identifier.
In some cases an application may need to work with identifiers from which
the generation has been stripped. A typical scenario in which this happens is
when iterating relationships in an entity type.
Return depth for entity in tree for the specified relationship.
Depth is determined by counting the number of targets encountered while
traversing up the relationship tree for rel. Only acyclic relationships are
supported.
Get an immutable pointer to a component.
This operation obtains a const pointer to the requested component. The
operation accepts the component entity id.
Get current interval value for the specified timer.
This operation returns the value set by ecs_set_interval. If the entity is
not a timer, the operation will return 0.
Combines get_mut + modifed in single operation.
This operation is a more efficient alternative to calling ecs_get_mut_id and
ecs_modified_id separately. This operation is only valid when the world is in
deferred mode, which ensures that the Modified event is not emitted before
the modification takes place.
Get a path identifier for an entity.
This operation creates a path that contains the names of the entities from
the specified parent to the provided entity, separated by the provided
separator. If no parent is provided the path will be relative to the root. If
a prefix is provided, the path will be prefixed by the prefix.
Get stage-specific world pointer.
Flecs threads can safely invoke the API as long as they have a private
context to write to, also referred to as the stage. This function returns a
pointer to a stage, disguised as a world pointer.
Get current stage id.
The stage id can be used by an application to learn about which stage it is
using, which typically corresponds with the worker thread id.
Get the target of a relationship.
This will return a target (second element of a pair) of the entity for the
specified relationship. The index allows for iterating through the targets,
if a single entity has multiple targets for the same relationship.
Get the target of a relationship for a given id.
This operation returns the first entity that has the provided id by following
the specified relationship. If the entity itself has the id then entity will
be returned. If the id cannot be found on the entity or by following the
relationship, the operation will return 0.
Get current timeout value for the specified timer.
This operation returns the value set by ecs_set_timeout. If no timer is
active for this entity, the operation returns 0.
Get the type for an id.
This function returnsthe type information for an id. The specified id can be
any valid id. For the rules on how type information is determined based on
id, see ecs_get_typeid.
Get the type for an id.
This operation returns the component id for an id, if the id is associated
with a type. For a regular component with a non-zero size (an entity with the
EcsComponent component) the operation will return the entity itself.
Process server requests.
This operation invokes the reply callback for each received request. No new
requests will be enqueued while processing requests.
Returns whether specified id is in use.
This operation returns whether an id is in use in the world. An id is in use
if it has been added to one or more tables.
Utility to match an id with a pattern.
This operation returns true if the provided pattern matches the provided
id. The pattern may contain a wildcard (or wildcards, when a pair).
Import a module.
This operation will load a modules and store the public module handles in the
handles_out out parameter. The module name will be used to verify if the
module was already loaded, in which case it won’t be reimported. The name
will be translated from PascalCase to an entity path (pascal.case) before the
lookup occurs.
Evaluate interpolated expressions in string.
This operation evaluates expressions in a string, and replaces them with
their evaluated result. Supported expression formats are:
Test whether an entity is alive.
Entities are alive after they are created, and become not alive when they are
deleted. Operations that return alive ids are (amongst others) ecs_new_id,
ecs_new_low_id and ecs_entity_init. Ids can be made alive with the ecs_ensure
function.
Test if component is enabled.
Test whether a component is currently enabled or disabled. This operation
will return true when the entity has the component and if it has not been
disabled by ecs_enable_component.
Returns whether the world is being deleted.
This operation can be used in callbacks like type hooks or observers to
detect if they are invoked while the world is being deleted.
Test whether an entity is valid.
Entities that are valid can be used with API functions. Using invalid
entities with API operations will cause the function to panic.
Count number of matched entities in query.
This operation returns the number of matched entities. If a query contains no
matched entities but still yields results (e.g. it has no terms with This
sources) the operation will return 0.
Get value of iterator variable as entity.
A variable can be interpreted as entity if it is set to an entity, or if it
is set to a table range with count 1.
Get value of iterator variable as table range.
A value can be interpreted as table range if it is set as table range, or if
it is set to an entity with a non-empty type (the entity must have at least
one component, tag or relationship in its type).
Get value of iterator variable as table.
A variable can be interpreted as table if it is set as table range with
both offset and count set to 0, or if offset is 0 and count matches the
number of elements in the table.
Test if iterator is true.
This operation will return true if the iterator returns at least one result.
This is especially useful in combination with fact-checking rules (see the
rules addon).
Progress any iterator.
This operation is useful in combination with iterators for which it is not
known what created them. Example use cases are functions that should accept
any kind of iterator (such as serializers) or iterators created from poly
objects.
Create iterator from poly object.
The provided poly object must have the iterable mixin. If an object is
provided that does not have the mixin, the function will assert.
Set value for iterator variable.
This constrains the iterator to return only results for which the variable
equals the specified value. The default value for all variables is
EcsWildcard, which means the variable can assume any value.
Serialize iterator into JSON string.
This operation will iterate the contents of the iterator and serialize them
to JSON. The function acccepts iterators from any source.
Convert iterator to vars
This operation converts an iterator to a variable array. This allows for
using iterator results in expressions. The operation only converts a
single result at a time, and does not progress the iterator.
Enable/disable logging time since last log.
By default deltatime is disabled. Note that enabling timestamps introduces
overhead as the logging code will need to obtain the current time.
Enable/disable logging timestamp.
By default timestamps are disabled. Note that enabling timestamps introduces
overhead as the logging code will need to obtain the current time.
Enable or disable log.
This will enable builtin log. For log to work, it will have to be
compiled in which requires defining one of the following macros:
Lookup an entity by name.
Returns an entity that matches the specified name. Only looks for entities in
the current scope (root if no scope is provided).
Lookup a child entity by name.
Returns an entity that matches the specified name. Only looks for entities in
the provided parent. If no parent is provided, look in the current scope (
root if no scope is provided).
Lookup an entity from a path.
Lookup an entity from a provided path, relative to the provided parent. The
operation will use the provided separator to tokenize the path expression. If
the provided path contains the prefix, the search will start from the root.
Lookup an entity by its symbol name.
This looks up an entity by symbol stored in (EcsIdentifier, EcsSymbol). The
operation does not take into account hierarchies.
Make a pair id.
This function is equivalent to using the ecs_pair macro, and is added for
convenience to make it easier for non C/C++ bindings to work with pairs.
Function/macro postfixes meaning:
_ptr: access ecs_map_val_t as void*
_ref: access ecs_map_val_t* as T**
_deref: dereferences a _ref
_alloc: if _ptr is NULL, alloc
_free: if _ptr is not NULL, free
Measure frame time.
Frame time measurements measure the total time passed in a single frame, and
how much of that time was spent on systems and on merging.
Merge world or stage.
When automatic merging is disabled, an application can call this
operation on either an individual stage, or on the world which will merge
all stages. This operation may only be called when staging is not enabled
(either after progress() or after readonly_end()).
Create a new metric.
Metrics are entities that store values measured from a range of different
properties in the ECS storage. Metrics provide a single unified interface to
discovering and reading these values, which can be useful for monitoring
utilities, or for debugging.
Create a new world with just the core module.
Same as ecs_init, but doesn’t import modules from addons. This operation is
faster than ecs_init and results in less memory utilization.
Signal that a component has been modified.
This operation is usually used after modifying a component value obtained by
ecs_get_mut_id. The operation will mark the component as dirty, and invoke
OnSet observers and hooks.
Find or create entity from path.
This operation will find or create an entity from a path, and will create any
intermediate entities if required. If the entity already exists, no entities
will be created.
Create new entity id.
This operation returns an unused entity id. This operation is guaranteed to
return an empty entity as it does not use values set by ecs_set_scope or
ecs_set_with.
Create new low id.
This operation returns a new low id. Entity ids start after the
FLECS_HI_COMPONENT_ID constant. This reserves a range of low ids for things
like components, and allows parts of the code to optimize operations.
Create new entity with (component) id.
This operation creates a new entity with an optional (component) id. When 0
is passed to the id paramter, no component is added to the new entity.
Default run action for observer.
This function can be called from a custom observer run action (see
ecs_observer_desc_t::run for more details). This function ensures that the
observer’s filter is applied to the iterator’s table, filters out duplicate
events and implements EcsMonitor logic.
Create observer.
Observers are like triggers, but can subscribe for multiple terms. An
observer only triggers when the source of the event meets all terms.
Create a new opaque type.
Opaque types are types of which the layout doesn’t match what can be modelled
with the primitives of the meta framework, but which have a structure
that can be described with meta primitives. Typical examples are STL types
such as std::string or std::vector, types with a nontrivial layout, and types
that only expose getter/setter methods.
Add override for (component) id.
Adding an override to an entity ensures that when the entity is instantiated
(by adding an IsA relationship to it) the component with the override is
copied to a component that is private to the instance. By default components
reachable through an IsA relationship are shared.
Test if an entity owns an id.
This operation returns true if the entity has the specified id. The operation
behaves the same as ecs_has_id, except that it will return false for
components that are inherited through an IsA relationship.
Parse expression into value.
This operation parses a flecs expression into the provided pointer. The
memory pointed to must be large enough to contain a value of the used type.
Parse plecs file.
This parses a plecs file and instantiates the entities in the world. This
operation is equivalent to loading the file contents and passing it to
ecs_plecs_from_str.
Serialize primitive value into string buffer.
Serializes a primitive value to an ecs_strbuf_t instance. This operation can
be reused by other serializers to avoid having to write boilerplate code that
serializes primitive values to a string.
Parse JSON string into value.
This operation parses a JSON expression into the provided pointer. The
memory pointed to must be large enough to contain a value of the used type.
Serialize value into expression string.
This operation serializes a value of the provided type to a string. The
memory pointed to must be large enough to contain a value of the used type.
Similar as ecs_ptr_to_expr, but serializes values to string.
Whereas the output of ecs_ptr_to_expr is a valid expression, the output of
ecs_ptr_to_str is a string representation of the value. In most cases the
output of the two operations is the same, but there are some differences:
Destroy a query.
This operation destroys a query and its resources. If the query is used as
the parent of subqueries, those subqueries will be orphaned and must be
deinitialized as well.
Get filter from a query.
This operation obtains a pointer to the internally constructed filter
of the query and can be used to introspect the query terms.
Get information about query group.
This operation returns information about a query group, including the group
context returned by the on_group_create callback.
Create a query.
This operation creates a query. Queries are used to iterate over entities
that match a filter and are the fastest way to find and iterate over entities
and their components.
Return a query iterator.
A query iterator lets an application iterate over entities that match the
specified query. If a sorting function is specified, the query will check
whether a resort is required upon creating the iterator.
Progress the query iterator.
This operation progresses the query iterator to the next table. The
iterator must have been initialized with ecs_query_iter. This operation
must be invoked at least once before interpreting the contents of the
iterator.
Fast alternative to ecs_query_next that only returns matched tables.
This operation only populates the ecs_iter_t::table field. To access the
matched components, call ecs_query_populate.
Returns whether query is orphaned.
When the parent query of a subquery is deleted, it is left in an orphaned
state. The only valid operation on an orphaned query is deleting it. Only
subqueries can be orphaned.
Set group to iterate for query iterator.
This operation limits the results returned by the query to only the selected
group id. The query must have a group_by function, and the iterator must
be a query iterator.
Skip a table while iterating.
This operation lets the query iterator know that a table was skipped while
iterating. A skipped table will not reset its changed state, and the query
will not update the dirty flags of the table for its out columns.
Enable randomizing initial time value of timers.
Intializes timers with a random time value, which can improve scheduling as
systems/timers for the same interval don’t all happen on the same tick.
Begin read access to entity.
This operation provides safe read access to the components of an entity.
Multiple simultaneous reads are allowed per entity.
Begin readonly mode.
Readonly mode guarantees that no mutations will occur on the world, which
makes the world safe to access from multiple threads. While the world is in
readonly mode, operations are deferred.
End readonly mode.
This operation ends readonly mode, and must be called after
ecs_readonly_begin. Operations that were deferred while the world was in
readonly mode will be flushed.
Get component from entity record.
This operation returns a pointer to a component for the entity
associated with the provided record. For safe access to the component, obtain
the record with ecs_read_begin or ecs_write_begin.
Create a component ref.
A ref is a handle to an entity + component which caches a small amount of
data to reduce overhead of repeatedly accessing the component. Use
ecs_ref_get to get the component data.
Remove all instances of the specified (component) id.
This will remove the specified id from all entities (tables). The id may be
a wildcard and/or a pair.
Remove a (component) id from an entity.
This operation removes a single (component) id to an entity. If the entity
does not have the id, this operation will have no side effects.
Find variable index.
This operation looks up the index of a variable in the rule. This index can
be used in operations like ecs_iter_set_var and ecs_iter_get_var.
Iterate a rule.
Note that rule iterators may allocate memory, and that unless the iterator
is iterated until completion, it may still hold resources. When stopping
iteration before ecs_rule_next has returned false, use ecs_iter_fini to
cleanup any remaining resources.
Populate variables from key-value string.
Convenience function to set rule variables from a key-value string separated
by comma’s. The string must have the followig format:
var_a: value, var_b: value
Convert rule to string with profile.
To use this you must set the EcsIterProfile flag on an iterator before
starting uteration:
it.flags |= EcsIterProfile
Test if variable is an entity.
Internally the rule engine has entity variables and table variables. When
iterating through rule variables (by using ecs_rule_variable_count) only
the values for entity variables are accessible. This operation enables an
appliction to check if a variable is an entity variable.
Run a specific system manually.
This operation runs a single system manually. It is an efficient way to
invoke logic on a set of entities, as manual systems are only matched to
tables at creation time or after creation time, when a new table is created.
Force aperiodic actions.
The world may delay certain operations until they are necessary for the
application to function correctly. This may cause observable side effects
such as delayed triggering of events, which can be inconvenient when for
example running a test suite.
Run pipeline.
This will run all systems in the provided pipeline. This operation may be
invoked from multiple threads, and only when staging is disabled, as the
pipeline manages staging and, if necessary, synchronization between threads.
Register action to be executed once after frame.
Post frame actions are typically used for calling operations that cannot be
invoked during iteration, such as changing the number of threads.
Load managed script.
A managed script tracks which entities it creates, and keeps those entities
synchronized when the contents of the script are updated. When the script is
updated, entities that are no longer in the new version will be deleted.
Search for component id in table type starting from an offset.
This operation is the same as ecs_search, but starts searching from an offset
in the table type.
Search for component/relationship id in table type starting from an offset.
This operation is the same as ecs_search_offset, but has the additional
capability of traversing relationships to find a component. For example, if
an application wants to find a component for either the provided table or a
prefab (using the IsA relationship) of that table, it could use the operation
like this:
Set alias for entity.
An entity can be looked up using its alias from the root scope without
providing the fully qualified name if its parent. An entity can only have
a single alias.
Enable/disable automerging for world or stage.
When automerging is enabled, staged data will automatically be merged with
the world when staging ends. This happens at the end of progress(), at a
sync point or when readonly_end() is called.
Set a world binding context.
Same as ecs_set_ctx but for binding context. A binding context is intended
specifically for language bindings to store binding specific data.
Set a world context.
This operation allows an application to register custom data with a world
that can be accessed anywhere where the application has the world.
Override the generation of an entity.
The generation count of an entity is increased each time an entity is deleted
and is used to test whether an entity id is alive.
Set a range for issueing new entity ids.
This function constrains the entity identifiers returned by ecs_new to the
specified range. This operation can be used to ensure that multiple processes
can run in the same simulation without requiring a central service that
coordinates issueing identifiers.
Register hooks for component.
Hooks allow for the execution of user code when components are constructed,
copied, moved, destructed, added, removed or set. Hooks can be assigned as
as long as a component has not yet been used (added to an entity).
Set the value of a component.
This operation allows an application to set the value of a component. The
operation is equivalent to calling ecs_get_mut_id followed by
ecs_modified_id. The operation will not modify the value of the passed in
component. If the component has a copy hook registered, it will be used to
copy in the component.
Set timer interval.
This operation will continously invoke systems associated with the timer
after the interval period expires. If the entity contains an existing timer,
the interval value will be reset.
Set search path for lookup operations.
This operation accepts an array of entity ids that will be used as search
scopes by lookup operations. The operation returns the current search path.
It is good practice to restore the old search path.
Set a name prefix for newly created entities.
This is a utility that lets C modules use prefixed names for C types and
C functions, while using names for the entity names that do not have the
prefix. The name prefix is currently only used by ECS_COMPONENT.
Set rate filter.
This operation initializes a rate filter. Rate filters sample tick sources
and tick at a configurable multiple. A rate filter is a tick source itself,
which means that rate filters can be chained.
Set the current scope.
This operation sets the scope of the current stage to the provided entity.
As a result new entities will be created in this scope, and lookups will be
relative to the provided scope.
Configure world to have N stages.
This initializes N stages, which allows applications to defer operations to
multiple isolated defer queues. This is typically used for applications with
multiple threads, where each thread gets its own queue, and commands are
merged when threads are synchronized.
Set target frames per second (FPS) for application.
Setting the target FPS ensures that ecs_progress is not invoked faster than
the specified FPS. When enabled, ecs_progress tracks the time passed since
the last invocation, and sleeps the remaining time of the frame (if any).
Set number of worker task threads.
ecs_set_task_threads is similar to ecs_set_threads, except threads are treated
as short-lived tasks and will be created and joined around each update of the world.
Creation and joining of these tasks will use the os_api_t tasks APIs rather than the
the standard thread API functions, although they may be the same if desired.
This function is useful for multithreading world updates using an external
asynchronous job system rather than long running threads by providing the APIs
to create tasks for your job system and then wait on their conclusion.
The operation may be called multiple times to reconfigure the number of task threads
used, but never while running a system / pipeline.
Calling ecs_set_task_threads will also end the use of threads setup with
ecs_set_threads and vice-versa
Set number of worker threads.
Setting this value to a value higher than 1 will start as many threads and
will cause systems to evenly distribute matched entities across threads. The
operation may be called multiple times to reconfigure the number of threads
used, but never while running a system / pipeline.
Calling ecs_set_threads will also end the use of task threads setup with
ecs_set_task_threads and vice-versa
Assign tick source to system.
Systems can be their own tick source, which can be any of the tick sources
(one shot timers, interval times and rate filters). However, in some cases it
is must be guaranteed that different systems tick on the exact same frame.
Set timer timeout.
This operation executes any systems associated with the timer after the
specified timeout value. If the entity contains an existing timer, the
timeout value will be reset. The timer can be started and stopped with
ecs_start_timer and ecs_stop_timer.
Restore a snapshot.
This operation restores the world to the state it was in when the specified
snapshot was taken. A snapshot can only be used once for restoring, as its
data replaces the data that is currently in the world.
This operation also resets the last issued entity handle, so any calls to
ecs_new may return entity ids that have been issued before restoring the
snapshot.
Create a filtered snapshot.
This operation is the same as ecs_snapshot_take, but accepts an iterator so
an application can control what is stored by the snapshot.
Test whether the current world is readonly.
This function allows the code to test whether the currently used world
is readonly or whether it allows for writing.
Write an escaped string.
Write an input string to an output string, escape characters where necessary.
To determine the size of the output string, call the operation with a NULL
argument for ‘out’, and use the returned size to allocate a string that is
large enough.
Get system binding context.
The binding context is a context typically used to attach any language
binding specific data that is needed when invoking a callback that is
implemented in another language.
Get system context.
This operation returns the context pointer set for the system. If
the provided entity is not a system, the function will return NULL.
Get the query object for a system.
Systems use queries under the hood. This enables an application to get access
to the underlying query object of a system. This can be useful when, for
example, an application needs to enable sorting for a system.
Get table that has all components of current table plus the specified id.
If the provided table already has the provided id, the operation will return
the provided table.
Return number of columns in table.
Similar to ecs_table_get_type(table)->count, except that the column count
only counts the number of components in a table.
Convert column index to type index.
Same as ecs_table_type_to_column_index, but converts from an index in the
column array to an index in the table type.
Returns the number of records in the table.
This operation returns the number of records that have been populated through
the regular (entity) API as well as the number of records that have been
inserted using the direct access API.
Find table from id array.
This operation finds or creates a table with the specified array of
(component) ids. The ids in the array must be sorted, and it may not contain
duplicate elements.
Get column index for id.
This operation returns the column index for an id in the table’s type. If the
id is not a component, the function will return -1.
Return depth for table in tree for relationship rel.
Depth is determined by counting the number of targets encountered while
traversing up the relationship tree for rel. Only acyclic relationships are
supported.
Test table for flags.
Test if table has all of the provided flags. See
include/flecs/private/api_flags.h for a list of table flags that can be used
with this function.
Lock or unlock table.
When a table is locked, modifications to it will throw an assert. When the
table is locked recursively, it will take an equal amount of unlock
operations to actually unlock the table.
Get table that has all components of current table minus the specified id.
If the provided table doesn’t have the provided id, the operation will return
the provided table.
Swaps two elements inside the table. This is useful for implementing custom
table sorting algorithms.
@param world The world
@param table The table to swap elements in
@param row_1 Table element to swap with row_2
@param row_2 Table element to swap with row_1
Convert type index to column index.
Tables have an array of columns for each component in the table. This array
does not include elements for tags, which means that the index for a
component in the table type is not necessarily the same as the index in the
column array. This operation converts from an index in the table type to an
index in the column array.
Return a chained term iterator.
A chained iterator applies a filter to the results of the input iterator. The
resulting iterator must be iterated with ecs_term_next.
Copy resources of a term to another term.
This operation copies one term to another term. If the source term contains
allocated resources (such as identifiers), they will be duplicated so that
no memory is shared between the terms.
Finalize term.
Ensure that all fields of a term are consistent and filled out. This
operation should be invoked before using and after assigning members to, or
parsing a term. When a term contains unresolved identifiers, this operation
will resolve and assign the identifiers. If the term contains any identifiers
that cannot be resolved, the operation will fail.
Iterator for a single (component) id.
A term iterator returns all entities (tables) that match a single (component)
id. The search for the matching set of entities (tables) is performed in
constant time.
Is term matched on 0 source.
This operation checks whether a term is matched on a 0 source. A 0 source is
a term that isn’t matched against anything, and can be used just to pass
(component) ids to a query iterator.
Move resources of a term to another term.
Same as copy, but moves resources from src, if src->move is set to true. If
src->move is not set to true, this operation will do a copy.
Progress a term iterator.
This operation progresses the term iterator to the next table. The
iterator must have been initialized with ecs_term_iter. This operation
must be invoked at least once before interpreting the contents of the
iterator.
Convert term to string expression.
Convert term to a string expression. The resulting expression is equivalent
to the same term, with the exception of And & Or operators.
Create a worker iterator.
Worker iterators can be used to equally divide the number of matched entities
across N resources (usually threads). Each resource will process the total
number of matched entities divided by ‘count’.
Begin exclusive write access to entity.
This operation provides safe exclusive access to the components of an entity
without the overhead of deferring operations.
An entity identifier.
Entity ids consist out of a number unique to the entity in the lower 32 bits,
and a counter used to track entity liveliness in the upper 32 bits. When an
id is recycled, its generation count is increased. This causes recycled ids
to be very large (>4 billion), which is normal.
Request callback.
Invoked for each valid request. The function should populate the reply and
return true. When the function returns false, the server will reply with a
404 (Not found) code.
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.
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.
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:
Function prototype for runnables (systems, observers).
The run callback overrides the default behavior for iterating through the
results of a runnable object.