Crate flecs

source ·

Re-exports

Modules

Macros

Structs

Constants

Statics

Traits

Functions

  • Module import
  • Module import
  • Module import
  • Module import
  • Module import
  • Module import
  • Module
  • Module import
  • Module import
  • Module
  • Module
  • 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.
  • Add specified path to entity. This operation is similar to ecs_new_from_path, but will instead add the path to an existing entity.
  • 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.
  • Set custom frame action. See ecs_app_run_frame.
  • Set custom run action. See ecs_app_run.
  • Create a new array type
  • 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.
  • Serialize array into JSON string buffer. Same as ecs_array_to_json_buf, but serializes to an ecs_strbuf_t instance.
  • Create allocated string from format
  • Return escaped string. Return escaped version of input string. Same as ecs_stresc, but returns an allocated string of the right size.
  • Free asynchronous stage. The provided stage must be an asynchronous stage. If a non-asynchronous stage is provided, the operation will fail.
  • 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.
  • Register action to be executed when world is destroyed. Fini actions are typically used when a module needs to clean up before a world shuts down.
  • Create a new bitmask type
  • Bulk create/populate new entities. This operation bulk inserts a list of new or predefined entities into a single table.
  • Create N new entities. This operation is the same as ecs_new_w_id, but creates N entities instead of one.
  • Iterator for a parent’s children. This operation is equivalent to a term iterator for (ChildOf, parent). Iterate the result with ecs_children_next.
  • Progress a children iterator. Equivalent to ecs_term_next.
  • Write an escaped character. Write a character to an output string, insert escape character if necessary.
  • Parse an escaped character. Parse a character with a potential escape sequence.
  • Clear all components. This operation will remove all components from an entity.
  • 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.
  • Commit (move) entity to a table. This operation moves an entity from its current table to the specified table. This may cause the following actions:
  • 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.
  • Count entities that have the specified id. Returns the number of entities that have the specified id.
  • Constructor that zeromem’s a component value
  • 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.
  • End block of operations to defer. See defer_begin.
  • Resume deferring. See ecs_defer_suspend.
  • Suspend deferring but do not flush queue. This operation can be used to do an undeferred operation while not flushing the operations in the queue.
  • 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.
  • Delete all entities with the specified id. This will delete all entities (tables) that have the specified id. The id may be a wildcard and/or a pair.
  • Tracing
  • 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.
  • Get brief description from entity.
  • Get color from entity.
  • Get detailed description from entity.
  • Get link to external documentation from entity.
  • Get human readable name from entity. If entity does not have an explicit human readable name, this operation will return the entity name.
  • Add brief description to entity.
  • Add color to entity. UIs can use color as hint to improve visualizing entities.
  • Add detailed description to entity.
  • Add link to external documentation to entity.
  • 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 ‘*’.
  • Send event. This sends an event to matching triggers & is the mechanism used by flecs itself to send OnAdd, OnRemove, etc events.
  • 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.
  • Convert entity to string. Same as combining:
  • 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.
  • Serialize entity into JSON string buffer. Same as ecs_entity_to_json, but serializes to an ecs_strbuf_t instance.
  • Create a new enum type
  • Test whether an entity exists. Similar as ecs_is_alive, but ignores entity generation count.
  • 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.
  • Return id matched for field.
  • 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.
  • Test whether field is set.
  • Test whether the field is writeonly. This operation returns whether this is a writeonly field. Writeonly terms are annotated with [out].
  • Return field type size. Return type size of the field. Returns 0 if the field has no data.
  • Return field source. The field source is the entity on which the field was matched.
  • 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.
  • Copy resources of one filter to another.
  • 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.
  • Deinitialize filter. Free resources associated with filter.
  • 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.
  • Return a filter iterator. A filter iterator lets an application iterate over entities that match the specified filter.
  • Move resources of one filter to another.
  • 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.
  • Same as ecs_filter_next, but always instanced. See instanced property of ecs_filter_desc_t.
  • Get pivot term for filter. The pivot term is the term that matches the smallest set of tables, and is a good default starting point for a search.
  • Convert filter to string expression. Convert filter terms to a string expression. The resulting expression can be parsed to create the same filter.
  • Delete a world. This operation deletes the world, and everything it contains.
  • 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.
  • End frame. This operation must be called at the end of the frame, and always after ecs_frame_begin.
  • 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.
  • Get the world binding context. This operation retrieves a previously set world binding context.
  • Get the world context. This operation retrieves a previously set world context.
  • 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 entity from poly.
  • Get hooks for component.
  • 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.
  • Get current lookup path. Returns value set by ecs_set_lookup_path.
  • Get the largest issued entity id (not counting generation).
  • Get a mutable pointer to a component. This operation returns a mutable pointer to a component. If the component did not yet exist, it will be added.
  • 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 the name of an entity. This will return the name stored in (EcsIdentifier, EcsName).
  • Get parent (target of ChildOf relationship) for entity. This operation is the same as calling: ecs_get_target(world, entity, EcsChildOf, 0);
  • 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.
  • Write path identifier to buffer. Same as ecs_get_path_w_sep, but writes result to an ecs_strbuf_t.
  • Get the current pipeline. This operation gets the current pipeline.
  • Get the current scope. Get the scope set by ecs_set_scope. If no scope is set, this operation will return 0.
  • 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 number of configured stages. Return number of stages set by ecs_set_stage_count.
  • 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 symbol of an entity. This will return the symbol stored in (EcsIdentifier, EcsSymbol).
  • Get the table of an entity.
  • 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 of an entity.
  • 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.
  • Get current with id. Get the id set with ecs_set_with.
  • Get world from poly.
  • Get world info.
  • Test if an entity has an id. This operation returns true if the entity has or inherits the specified id.
  • Find header in request.
  • Find query parameter in request.
  • Get context provided in ecs_http_server_desc_t
  • Process server requests. This operation invokes the reply callback for each received request. No new requests will be enqueued while processing requests.
  • Destroy server. This operation will stop the server if it was still running.
  • Emulate a request. The request string must be a valid HTTP request. A minimal example: GET /entity/flecs/core/World?label=true HTTP/1.1
  • Create server. Use ecs_http_server_start to start receiving requests.
  • Convenience wrapper around ecs_http_server_request.
  • Start server. After this operation the server will be able to accept requests.
  • Stop server. After this operation no new requests can be received.
  • Convert id flag to string. This operation converts a id flag to a string.
  • Get flags associated with id. This operation returns the internal flags (see api_flags.h) that are associated with the provided id.
  • 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 check if id is a pair.
  • Returns whether specified id a tag. This operation returns whether the specified type is a tag (a component without data/size).
  • Return whether represents a union. This operation returns whether the specified type represents a union. Only pair ids can be unions.
  • Utility to check if id is valid. A valid id is an id that can be added to an entity. Invalid ids are:
  • Utility to check if id is a wildcard.
  • 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).
  • Convert id to string. This operation interprets the structure of an id and converts it to a string.
  • Write id string to buffer. Same as ecs_id_str but writes result to ecs_strbuf_t.
  • 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.
  • Same as ecs_import, but with name to scope conversion. PascalCase names are automatically converted to scoped names.
  • Import a module from a library. Similar to ecs_import, except that this operation will attempt to load the module from a dynamic library.
  • Create a new world. This operation automatically imports modules from addons Flecs has been built with, except when the module specifies otherwise.
  • Create a new world with arguments. Same as ecs_init, but allows passing in command line arguments. Command line arguments are used to:
  • 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 deferring is enabled for current stage.
  • 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.
  • Cleanup iterator resources. This operation cleans up any resources associated with the iterator.
  • Get first matching entity from iterator. After this operation the application should treat the iterator as if it has been iterated until completion.
  • 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.
  • Same as ecs_iter_set_var, but for a range of entities This constrains the variable to a range of entities in a table.
  • Same as ecs_iter_set_var, but for a table. This constrains the variable to all entities in a table.
  • Convert iterator to string. Prints the contents of an iterator to a string. Useful for debugging and/or testing the output of an iterator.
  • 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.
  • Serialize iterator into JSON string buffer. Same as ecs_iter_to_json, but serializes to an ecs_strbuf_t instance.
  • 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.
  • Returns whether variable is constrained. This operation returns true for variables set by one of the ecs_iter_set_var* operations.
  • Enable/disable tracing with colors. By default colors are enabled.
  • 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.
  • Get current log level.
  • Get last logged error code. Calling this operation resets the error code.
  • Decrease log stack. This operation decreases the indent_ value of the OS API and can be useful to make nested behavior more visible.
  • Increase log stack. This operation increases the indent_ value of the OS API and can be useful to make nested behavior more visible.
  • 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.
  • Remove all elements from map.
  • Copy map.
  • Get or insert element for key.
  • Get or insert pointer element for key, allocate if the pointer is NULL
  • Deinitialize map.
  • Get element for key, returns NULL if they key doesn’t exist.
  • Get element as pointer (auto-dereferences _ptr)
  • Initialize new map.
  • Initialize new map if uninitialized, leave as is otherwise
  • Initialize new map.
  • Insert element for key.
  • Insert pointer element for key, populate with new allocation.
  • Return iterator to map contents.
  • Obtain next element in map from iterator.
  • 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
  • Remove key from map.
  • Remove pointer element, free if not NULL
  • 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.
  • Measure system time. System time measurements measure the time spent in each system.
  • 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()).
  • Move cursor to member, supports dot-separated nested members
  • Move cursor to a element
  • Populate meta information from type descriptor.
  • Get field value as boolean.
  • Get field value as char.
  • Get field value as entity. This operation does not perform conversions.
  • Get field value as float.
  • Get field value as signed integer.
  • Get member name of current member
  • Get member entity of current member
  • Get pointer to current field
  • Get field value as string. This operation does not perform conversions. If the field is not a string, this operation will fail.
  • Get type of current element.
  • Get field value as unsigned integer.
  • Get unit of current element.
  • Is the current scope a collection?
  • Move cursor to member
  • Move cursor to next field
  • Pop a struct or collection scope (must follow a push)
  • Convert pointer of primitive kind to float.
  • Push a scope (required/only valid for structs & collections)
  • Set field with boolean value
  • Set field with char value
  • Set field with entity value
  • Set field with float value
  • Set field with int value
  • Set field with null value
  • Set field with string value
  • Set field with string literal value (has enclosing “”)
  • Set field with uint value
  • Set field with dynamic value
  • Copy measurement
  • 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.
  • Reduce all measurements from a window into a single measurement.
  • Reduce last measurement into previous measurement
  • 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.
  • Register a new module.
  • 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.
  • Create new entity in table. This operation creates a new entity in the specified table.
  • 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.
  • Get observer binding ctx. Return the value set in ecs_observer_desc_t::binding_ctx.
  • Get observer ctx. Return the value set in ecs_observer_desc_t::ctx.
  • 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.
  • Logging
  • Are dynamic library functions available?
  • Are heap functions available?
  • Are logging functions available?
  • Are module path functions available?
  • Are task functions available?
  • Are threading functions available?
  • Are time functions available?
  • 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.
  • Create a paged iterator. Paged iterators limit the results to those starting from ‘offset’, and will return at most ‘limit’ results.
  • Progress a paged iterator. Progresses an iterator created by ecs_page_iter.
  • Parse digit. This function will parse until the first non-digit character is found. The provided expression must contain at least one digit character.
  • 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 expression token. Expression tokens can contain more characters (such as ‘|’) than tokens parsed by the query (term) parser.
  • Utility function to parse an identifier
  • Parse term in expression. This operation parses a single term in an expression and returns a pointer to the next term expression.
  • Parse a single token. This function can be used as simple tokenizer by other parsers.
  • Skip whitespace characters. This function skips whitespace characters. Does not skip newlines.
  • Skip whitespace and newline characters. This function skips whitespace characters.
  • Create a custom pipeline.
  • Copy last measurement to destination. This operation copies the last measurement into the destination. It does not modify the cursor.
  • Free pipeline stats.
  • Get pipeline statistics. Obtain statistics for the provided pipeline.
  • Reduce source measurement window into single destination measurement
  • Reduce last measurement into previous measurement, restore old value.
  • Repeat last measurement.
  • 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.
  • Parse plecs string. This parses a plecs string and instantiates the entities in the world.
  • Test if pointer is of specified type. Usage: ecs_poly_is(ptr, ecs_world_t)
  • Create a new primitive type
  • 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.
  • Logging functions (do nothing when logging is enabled)
  • Progress a world. This operation progresses the world by running all systems that are both enabled and periodic on their matching entities.
  • 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.
  • Serialize value into expression buffer. Same as ecs_ptr_to_expr, but serializes to an ecs_strbuf_t instance.
  • Serialize value into JSON string. Same as ecs_array_to_json, with count = 0.
  • Serialize value into JSON string buffer. Same as ecs_ptr_to_json, but serializes to an ecs_strbuf_t instance.
  • 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:
  • Serialize value into string buffer. Same as ecs_ptr_to_str, but serializes to an ecs_strbuf_t instance.
  • Create a new quantity
  • Returns whether the query data changed since the last iteration. The operation will return true after:
  • Returns number of empty tables query matched with.
  • Returns number of entities query matched with. This operation iterates all non-empty tables in the query cache to find the total number of entities.
  • 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 query binding ctx. Return the value set in ecs_query_desc_t::binding_ctx.
  • Get query ctx. Return the value set in ecs_query_desc_t::ctx.
  • 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 context of query group. This operation returns the context of a query group as returned by the on_group_create callback.
  • 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.
  • Same as ecs_query_next, but always instanced. See “instanced” property of ecs_filter_desc_t.
  • 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.
  • Populate iterator fields. This operation can be combined with ecs_query_next_table to populate the iterator fields for the current table.
  • 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.
  • Copy last measurement from source to destination.
  • Get query statistics. Obtain statistics for the provided query.
  • Reduce source measurement window into single destination measurement.
  • Reduce last measurement into previous measurement, restore old value.
  • Repeat last measurement.
  • Convert query to string.
  • Returns number of tables query matched with.
  • Signal exit This operation signals that the application should quit. It will cause ecs_progress to return false.
  • 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.
  • End read access to entity. This operation ends read access, and must be called after ecs_read_begin.
  • 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.
  • Find record for entity.
  • Get component pointer from column/record.
  • Get entity corresponding with record. This operation only works for entities that are not empty.
  • 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.
  • Same as ecs_record_get_id, but returns a mutable pointer. For safe access to the component, obtain the record with ecs_write_begin.
  • Test if entity for record has component.
  • Get component from ref. Get component pointer from ref. The ref must be created with ecs_ref_init.
  • 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.
  • Update ref. Ensures contents of ref are up to date. Same as ecs_ref_get_id, but does not return pointer to component id.
  • 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.
  • Reset world clock. Reset the clock that keeps track of the total time passed in the simulation.
  • Reset time value of timer to 0. This operation resets the timer value to 0.
  • Cleanup REST HTTP server. The server must have been created with ecs_rest_server_init.
  • Create HTTP server for REST API. This allows for the creation of a REST server that can be managed by the application without using Flecs systems.
  • 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.
  • Delete a rule.
  • Obtain filter from rule. This operation returns the filter with which the rule was created.
  • Create a rule. A rule accepts the same descriptor as a filter, but has the additional ability to use query variables.
  • 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.
  • Progress rule iterator.
  • Progress instanced iterator. Should not be called unless you know what you’re doing :-)
  • 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 a string. This will convert the rule program to a string which can aid in debugging the behavior of a rule.
  • Convert rule to string with profile. To use this you must set the EcsIterProfile flag on an iterator before starting uteration: it.flags |= EcsIterProfile
  • Return number of variables in rule.
  • 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.
  • Get variable name. This operation returns the variable name for an index.
  • 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.
  • Run system with offset/limit and type filter. This operation is the same as ecs_run, but filters the entities that will be iterated by the system.
  • Same as ecs_run, but subdivides entities across number of provided stages.
  • Clear all entities associated with script.
  • 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.
  • Update script with new code.
  • Search for component id in table type. This operation returns the index of first occurrance of the id in the table type. The id may be a wildcard.
  • 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 the name of an entity. This will set or overwrite the name of an entity. If no entity is provided, a new entity will be created.
  • 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 a custom pipeline. This operation sets the pipeline to run when ecs_progress is invoked.
  • 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 the symbol of an entity. This will set or overwrite the symbol of an entity. If no entity is provided, a new entity will be created.
  • 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 time scale. Increase or decrease simulation speed by the provided multiplier.
  • 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.
  • Set current with id. New entities are automatically created with the specified id.
  • Should current level be logged. This operation returns true when the specified log level should be logged with the current log level.
  • Return whether a quit has been signaled.
  • Sleep with floating point time
  • Free snapshot resources. This frees resources associated with a snapshot without restoring it.
  • Obtain iterator to snapshot data.
  • Progress snapshot iterator.
  • 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 snapshot. This operation makes a copy of the current state of the world.
  • 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.
  • Publicly exposed APIs The flecs_ functions aren’t exposed directly as this can cause some optimizers to not consider them for link time optimization.
  • Test whether provided stage is asynchronous.
  • 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.
  • Start timer. This operation resets the timer and starts it with the specified timeout.
  • Stop timer This operation stops a timer from triggering.
  • Append format string to a buffer. Returns false when max is reached, true when there is still space
  • Append boolean to buffer. Returns false when max is reached, true when there is still space
  • Append character to buffer. Returns false when max is reached, true when there is still space
  • Append float to buffer. Returns false when max is reached, true when there is still space
  • Append int to buffer. Returns false when max is reached, true when there is still space
  • Append string to buffer. Returns false when max is reached, true when there is still space
  • Append string to buffer, transfer ownership to buffer. Returns false when max is reached, true when there is still space
  • Append string to buffer, do not free/modify string. Returns false when max is reached, true when there is still space
  • Append string to buffer, transfer ownership to buffer. Returns false when max is reached, true when there is still space
  • Append string to buffer, transfer ownership to buffer. Returns false when max is reached, true when there is still space
  • Append n characters to buffer. Returns false when max is reached, true when there is still space
  • Return result string
  • Return small string from first element (appends \0)
  • Append formatted string as a new element in list
  • Append character to as new element in list.
  • Append string as a new element in list
  • Append string as a new element in list
  • Insert a new element in list
  • Pop a new list
  • Push a list
  • Append source buffer to destination buffer. Returns false when max is reached, true when there is still space
  • Reset buffer without returning a string
  • Append format string with argument list to a buffer. Returns false when max is reached, true when there is still space
  • Get description for error code
  • 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.
  • Remove generation from entity id.
  • Create a new struct type
  • 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.
  • Create a system
  • Copy last measurement from source to destination.
  • Get system statistics. Obtain statistics for the provided system.
  • Reduce source measurement window into single destination measurement
  • Reduce last measurement into previous measurement, restore old value.
  • Repeat last measurement.
  • 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 from table by column index. This operation returns the component array for the provided index.
  • 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.
  • Get column size from table. This operation returns the component size for the provided index.
  • 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.
  • Get column from table by component id. This operation returns the component array for the provided component id.
  • Get type for table. The table type is a vector that contains all component, tag and pair ids.
  • Get type index for id. This operation returns the index for an id in the table’s type.
  • 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.
  • Test if table has id. Same as ecs_table_get_type_index(world, table, id) != -1.
  • 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.
  • Convert table to string. Same as ecs_type_str(world, ecs_table_get_type(table)). The result of this operation must be freed with ecs_os_free.
  • 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.
  • Unlock a table. Must be called after calling ecs_table_lock.
  • 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.
  • Free resources of term. This operation frees all resources (such as identifiers) of a term. The term itself is not freed.
  • Test whether term id is set.
  • Test whether a term is set. This operation can be used to test whether a term has been initialized with values or whether it is empty.
  • 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.
  • Is term matched on $this variable. This operation checks whether a term is matched on the $this variable, which is the default source for queries.
  • 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.
  • Measure time since provided timestamp
  • Calculate difference between two timestamps
  • Convert time value to a double
  • Serialize type info to JSON. This serializes type information to JSON, and can be used to store/transmit the structure of a (component) value.
  • Serialize type info into JSON string buffer. Same as ecs_type_info_to_json, but serializes to an ecs_strbuf_t instance.
  • Convert type to string. The result of this operation must be freed with ecs_os_free.
  • Create a new unit
  • Create a new unit prefix
  • Returns true if task thread use have been requested.
  • Copy value.
  • Copy value.
  • Destruct a value
  • Destruct a value
  • Destruct a value, free storage
  • Construct a value in existing storage
  • Construct a value in existing storage
  • Move value.
  • Move construct value.
  • Move construct value.
  • Move value.
  • Construct a value in new storage
  • Construct a value in new storage
  • Declare variable in current scope
  • Declare variable in current scope from value. This operation takes ownership of the value. The value pointer must be allocated with ecs_value_new.
  • Cleanup variable storage
  • Init variable storage
  • Lookup variable in scope and parent scopes
  • Pop variable scope
  • Push variable scope
  • Create allocated string from format
  • Create a new vector type
  • 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’.
  • Progress a worker iterator. Progresses an iterator created by ecs_worker_iter.
  • Parse JSON object with multiple entities into the world. The format is the same as the one outputted by ecs_world_to_json.
  • Copy last measurement from source to destination.
  • Get world statistics.
  • Reduce source measurement window into single destination measurement.
  • Reduce last measurement into previous measurement, restore old value.
  • Repeat last measurement.
  • Serialize world into JSON string. This operation iterates the contents of the world to JSON. The operation is equivalent to the following code:
  • Serialize world into JSON string buffer. Same as ecs_world_to_json, but serializes to an ecs_strbuf_t instance.
  • Begin exclusive write access to entity. This operation provides safe exclusive access to the components of an entity without the overhead of deferring operations.
  • End exclusive write access to entity. This operation ends exclusive access, and must be called after ecs_write_begin.
  • Add element to sparse set, this generates or recycles an id
  • Remove all elements from sparse set
  • Get the number of alive elements in the sparse set.
  • Get or create element by (sparse) id.
  • Fast version of ensure, no liveliness checking
  • Get element by (sparse) id. The returned pointer is stable for the duration of the sparse set, as it is stored in the sparse array.
  • Like get_sparse, but don’t care whether element is alive or not.
  • Get value from sparse set by dense id. This function is useful in combination with flecs_sparse_count for iterating all values in the set.
  • Get pointer to ids (alive and not alive). Use with count() or size().
  • Initialize sparse set
  • Test if id is alive, which requires the generation count to match.
  • Get last issued id.
  • Generate or recycle a new id.
  • Remove an element
  • Override the generation count for a specific id
  • Same as flecs_sparse_get, but doesn’t assert if id is not alive.
  • Convert identifier to snake case

Type Aliases

Unions