# entity.h ## Overview
Implements an entity system. The purpose of the entity system is to support flexible game objects based on composition of simpler behaviors in a performant way. * An *entity* is an ID uniquely identifying a game object. * A *component* is a type of data that can be associated with an entity. * An *engine* is an update function that runs on all entities that have certain components. * A *system* is an update function that runs on the entire entity context. The difference between *engines* and *systems* is that engines are fed component data, where as systems are not. Thus, systems are useful when the data is stored externally from the components (for example to update a physics simulation), whereas *engines* are more efficient when the data is stored in the components. (You could use a *system* to update data in components, but it would be inefficient, because you would have to perform a lot of lookups to access the component data.) Entities live in a *simulation context*. When you create the context, you also define the components, engines and systems that exist in that context. A simple context that only offers a visual preview may only have a "rendering" engine running. A more advanced simulation may have engines and components for animation, sound, physics, etc. An entity always belongs to a specific context and entity IDs are only unique within the contexts. Entity IDs act as weak references. If you have an ID you can ask the context whether that entity is still alive or not. Note that there is no need for a rendering engine to exist. You can create a pure simulation context with no visualization. A single application may have multiple contexts running, each one representing its own isolated world. Each component defines a piece of POD data, that is stored for all entities that have the component. For example, a transform component may store position, rotation and scale data. In addition, a component may also have a *manager* object that gets notified whenever a components is added to or removed from an entity. The manager can store additional data that doesn't fit in the POD data block, such an array or a list. This data can only be accessed by communicating with the manager. Entities can be built up manually, by adding components, or they can be created from entity assets -- templates for how to build an entity. Entity assets are stored in The Truth. Multiple entities can be instanced from a single asset.
## Index
Truth configuration
`TM_TT_TYPE__ENTITY_SORT_VALUE`
`TM_TT_TYPE_HASH__ENTITY_SORT_VALUE`
`enum TM_TT_PROP__ENTITY_SORT_VALUE`
`TM_TT_TYPE__ENTITY`
`TM_TT_TYPE_HASH__ENTITY`
`enum TM_TT_PROP__ENTITY`

Opaque types
`tm_entity_context_o`
`tm_entity_commands_o`

Entity thumbnail interface
`tm_entity_thumbnail_provider_o`

`struct tm_entity_thumbnail_provider_i`
`inst`
`has_image_of_asset()`
`get_image_of_asset()`
`mark_image_of_asset_used()`

`tm_entity_thumbnail_provider_i_version`

Component configuration
`TM_MAX_COMPONENTS_IN_CONTEXT`
`struct tm_component_mask_t`
`tm_component_manager_o`

`struct tm_component_gamestate_representation_i`
`size`
`compute_initial_asset_hash_immediately`
`lazy_component_serialization`
`restore_sort_order`
`user_data`
`serialize()`
`deserialize()`
`compute_hash()`
`compute_asset_hash()`
`loaded()`
`num_shared_members`
`shared_members`

`struct tm_component_persistence_i`
`manual_tracking`
`num_members`
`members`

`struct tm_member_network_replication_t`

`struct tm_component_network_replication_i`
`watch_timer`
`num_members`
`members`
`member_replication`

`struct tm_component_i`
`name`
`bytes`
`default_data`
`manager`
`components_created()`
`load_asset()`
`asset_loaded()`
`asset_loaded_sort_order`
`asset_reloaded()`
`add()`
`remove()`
`destroy()`
`debug_draw()`
`debug_draw_settings`
`gamestate_representation`
`persistence`
`network_replication`
`automatically_call_remove_when_destroying`
`automatically_call_remove_when_reloading`

`tm_entity_create_component_i`
`tm_entity_create_component_i_version`

Engines and systems
`TM_MAX_COMPONENTS_FOR_ENGINE`
`struct tm_engine_update_array_t`
`struct tm_entity_blackboard_value_t`
`struct tm_engine_update_set_t`
`tm_engine_o`
`TM_MAX_DEPENDENCIES_FOR_ENGINE`
`TM_PHASE__ANIMATION`
`TM_PHASE__PHYSICS`
`TM_PHASE__GRAPH`
`TM_PHASE__CAMERA`
`TM_PHASE__RENDER`

`struct tm_engine_system_common_i`
`ui_name`
`hash`
`disabled`
`exclusive`
`num_components`
`components`
`writes`
`before_me`
`after_me`
`phase`

`struct tm_engine_i`
`TM_INHERITS()`
`inst`
`update()`
`num_excluded`
`excluded`
`filter()`

`tm_entity_system_o`

`struct tm_entity_system_i`
`TM_INHERITS()`
`inst`
`inited`
`init()`
`update()`
`shutdown()`
`hot_reload()`

`tm_entity_register_engines_i`
`tm_entity_register_engines_simulation_i`
`tm_entity_register_engines_simulation_i_version`
`tm_entity_register_engines_editor_i`
`tm_entity_register_engines_editor_i_version`

Blackboard
`TM_ENTITY_BB__SIMULATION_SPEED`
`TM_ENTITY_BB__DELTA_TIME`
`TM_ENTITY_BB__TIME`
`TM_ENTITY_BB__WALL_DELTA_TIME`
`TM_ENTITY_BB__WALL_TIME`
`TM_ENTITY_BB__UI`
`TM_ENTITY_BB__UI_STYLE`
`TM_ENTITY_BB__UI_RECT`
`TM_ENTITY_BB__UI_VIEWPORT_RECT`
`TM_ENTITY_BB__UI_SCALE_FACTOR`
`TM_ENTITY_BB__WINDOW`
`TM_ENTITY_BB__CAMERA`
`TM_ENTITY_BB__CAMERA_TRANSFORM`
`TM_ENTITY_BB__EDITOR`
`TM_ENTITY_BB__ASSET_ROOT`
`TM_ENTITY_BB__VIEWER`

Visual entity picker
`enum tm_entity_visual_picker_state`
`TM_ENTITY_VISUAL_PICKER_RESULT_NUM_ASSSETS_MENU_PICK`
`struct tm_entity_visual_picker_result_t`
`tm_entity_visual_picker_o`

`struct tm_entity_visual_picker_i`
`inst`
`pick()`

`tm_entity_visual_picker_i_version`

API
`enum tm_entity_create_components`

`struct tm_entity_listener_i`
`man`
`notify_e`
`notify_c`
`notify()`

`struct tm_entity_event_listener_i`
`inst`
`user_data`
`notify()`

`struct tm_entity_array_t`
`struct tm_entity_set_t`

`struct tm_entity_api`


`create_context()`
`destroy_context()`
`set_debug_name()`
`debug_name()`
`create_components()`
`register_component()`
`disable_component()`
`num_components()`
`component()`
`register_engine()`
`remove_engine()`
`registered_engines()`
`register_system()`
`remove_system()`
`registered_systems()`
`the_truth()`
`create_child_allocator()`
`destroy_child_allocator()`


`create_entity()`
`batch_create_entity()`
`create_entity_from_mask()`
`batch_create_entity_from_mask()`
`create_entity_from_asset()`
`batch_create_entity_from_asset()`
`create_entity_from_asset_with_world_transform()`
`batch_create_entity_from_asset_with_world_transforms()`
`create_network_entity()`
`destroy_entity()`
`batch_destroy_entity()`
`queue_destroy_entities()`
`clear_world()`
`is_alive()`


`num_entities()`
`entities_matching()`
`flatten_set()`
`asset_parent()`
`asset()`
`find_first_entity_from_asset()`
`find_entities_from_assets()`
`resolve_asset_reference()`
`resolve_asset_path()`


`lookup_component_type()`
`component_manager()`
`component_manager_by_hash()`
`create_component_mask()`
`component_mask()`
`add_component()`
`has_component()`
`read_component()`
`read_component_by_hash()`
`write_component()`
`write_component_by_hash()`
`remove_component()`


`propagate_asset_changes()`
`propagate_listen_to()`
`mark_asset_as_propagated()`


`update()`
`run_engine()`
`run_engine_with_commands()`
`flush_command_queues()`


`set_blackboard_double()`
`set_blackboard_ptr()`
`has_blackboard()`
`get_blackboard_double()`
`get_blackboard_ptr()`


`listen()`
`unlisten()`
`notify()`
`listen_event()`
`unlisten_event()`
`unlisten_all()`
`notify_event()`


`set_tag_debug_draw()`
`set_entity_debug_draw()`
`get_all_debug_draws()`
`has_tag_debug_draw()`
`has_entity_debug_draw()`
`clear_debug_draw()`
`debug_draw()`


`propagate_persistence_changes_to_gamestate()`
`propagate_network_replication_changes_to_gamestate()`
`override_component_persistence()`
`override_component_network_replication()`
`set_entity_persistence()`
`set_entity_replication()`
`entity_is_persistent()`
`entity_is_replicated()`
`lookup_entity_from_gamestate_id()`

`tm_entity_api_version`
`ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG`
`ENTITY_GAMESTATE_PERSISTENCE_CONFIG`
`union tm_entity_command_entity_handle_t`

`struct tm_entity_commands_api`
`create_entity_from_mask()`
`batch_create_entity_from_mask()`
`create_entity_from_asset()`
`batch_create_entity_from_asset()`
`destroy_entity()`
`batch_destroy_entity()`
`clear_world()`
`add_component()`
`remove_component()`
`add_component_by_handle()`
`register_engine()`
`remove_engine()`
`register_system()`
`remove_system()`

`tm_entity_commands_api_version`
`tm_entity_mask_has_component()`
`tm_entity_mask_add_component()`
`tm_entity_mask_remove_component()`
## API

Truth configuration

### `TM_TT_TYPE__ENTITY_SORT_VALUE`
~~~c #define TM_TT_TYPE__ENTITY_SORT_VALUE "tm_entity_sort_value" ~~~
### `TM_TT_TYPE_HASH__ENTITY_SORT_VALUE`
~~~c #define TM_TT_TYPE_HASH__ENTITY_SORT_VALUE TM_STATIC_HASH("tm_entity_sort_value", 0xeaaf394705f83715ULL) ~~~
### `enum TM_TT_PROP__ENTITY_SORT_VALUE`
~~~c enum TM_TT_PROP__ENTITY_SORT_VALUE { TM_TT_PROP__ENTITY__SORT_VALUE_CHILD, // reference [[TM_TT_TYPE__ANYTHING]] TM_TT_PROP__ENTITY__SORT_VALUE_VALUE, // double }; ~~~
### `TM_TT_TYPE__ENTITY`
~~~c #define TM_TT_TYPE__ENTITY "tm_entity" ~~~
### `TM_TT_TYPE_HASH__ENTITY`
~~~c #define TM_TT_TYPE_HASH__ENTITY TM_STATIC_HASH("tm_entity", 0xff156da2e01c4a3dULL) ~~~
### `enum TM_TT_PROP__ENTITY`
~~~c enum TM_TT_PROP__ENTITY { TM_TT_PROP__ENTITY__NAME, // string TM_TT_PROP__ENTITY__COMPONENTS, // subobject_set(TM_TT_TYPE__*_COMPONENT) TM_TT_PROP__ENTITY__CHILDREN, // subobject_set [[TM_TT_TYPE__ENTITY]] TM_TT_PROP__ENTITY__CHILD_SORT_VALUES, // subobject_set [[TM_TT_TYPE__ENTITY_SORT_VALUE]] TM_TT_PROP__ENTITY__NON_PERSISTENT, // bool TM_TT_PROP__ENTITY__NON_REPLICATED, // bool }; ~~~

Opaque types

### `tm_entity_context_o`
~~~c typedef struct tm_entity_context_o tm_entity_context_o; ~~~ Opaque object representing an entity context.
### `tm_entity_commands_o`
~~~c typedef struct tm_entity_commands_o tm_entity_commands_o; ~~~ Opaque object representing a buffer of entity commands.

Entity thumbnail interface

### `tm_entity_thumbnail_provider_o`
~~~c typedef struct tm_entity_thumbnail_provider_o tm_entity_thumbnail_provider_o; ~~~
### `struct tm_entity_thumbnail_provider_i`
#### `inst` ~~~c tm_entity_thumbnail_provider_o *inst; ~~~ #### `has_image_of_asset()` ~~~c bool (*has_image_of_asset)(tm_entity_thumbnail_provider_o *inst, tm_tt_id_t asset); ~~~ #### `get_image_of_asset()` ~~~c void (*get_image_of_asset)(tm_entity_thumbnail_provider_o *inst, tm_tt_id_t asset, struct tm_renderer_handle_t *img, struct tm_renderer_image_desc_t *img_desc); ~~~ #### `mark_image_of_asset_used()` ~~~c void (*mark_image_of_asset_used)(tm_entity_thumbnail_provider_o *inst, tm_tt_id_t asset); ~~~
### `tm_entity_thumbnail_provider_i_version`
~~~c #define tm_entity_thumbnail_provider_i_version TM_VERSION(1, 0, 0) ~~~

Component configuration

### `TM_MAX_COMPONENTS_IN_CONTEXT`
~~~c #define TM_MAX_COMPONENTS_IN_CONTEXT 1024 ~~~ The maximum number of components that we can have in a context.
### `struct tm_component_mask_t`
Mask used to match a set of entity components. ~~~c typedef struct tm_component_mask_t { uint64_t bits[TM_MAX_COMPONENTS_IN_CONTEXT / 64]; } tm_component_mask_t; ~~~
### `tm_component_manager_o`
~~~c typedef struct tm_component_manager_o tm_component_manager_o; ~~~ Opaque object representing the manager for a component. This will be cast to different concrete types, depending on the type of the component.
### `struct tm_component_gamestate_representation_i`
Specifies how a component is persisted to the Gamestate. Beware, data migration not yet supported. Components get persisted as "structs" in the Gamestate with the same name as the component name. The struct is a binary chunk of `size` bytes that can be generated in one of two ways: * The `serialize()` and `deserialize()` functions are used to serialize the data into a binary buffer of `size` bytes. They are not mandatory if `size` is equal to the "raw" size of the component. If that's the case we will just copy the raw bytes of the component to the Gamestate. #### `size` ~~~c uint32_t size; ~~~ Size in bytes of the component's Persistent Gamestate struct, cannot be zero. #### `compute_initial_asset_hash_immediately` ~~~c bool compute_initial_asset_hash_immediately; ~~~ Determines if the hash of the components can be computed lazily. This is only considered when creating Entity from Assets, as otherwise we _Must_ serialize the components to the Gamestate in order to not loose it. Only useful if `manual_tracking` is set to *false*. If *true*, the hash of this component will be computed and stored immediately after `asset_loaded()` is called. If *false*, the hash of this component will be computed lazily when `propagate_persistence_changes_to_gamestate()` is called. #### `lazy_component_serialization` ~~~c bool lazy_component_serialization; ~~~ Optional. If set to true, a component won't be automatically serialized to the Gamestate when `add_component()` is called. This is useful for "implicit" components where the component is added after the world has been created (for example Physx components) but you actually now how to reconstruct them. #### `restore_sort_order` ~~~c float restore_sort_order; ~~~ Optional. Used to control the order in which components are restored when the Gamestate is loaded. Components with a lower `restore_sort_order` are restored first. This might be needed, because some components depend on other components existing to be restored correctly. !!! TODO: GAMESTATE-REVIEW It's a bit problematic to have a single float for this that needs to be synchronized across different components in different plugins. Maybe something like the before/after order of engine updates would work better, though that's also a more complicated model. #### `user_data` ~~~c void *user_data; ~~~ Optional. User data for the persistance layer. #### `serialize()` ~~~c void (*serialize)(struct tm_entity_context_o *ctx, struct tm_gamestate_o *gamestate, tm_entity_t e, tm_component_type_t component, void *buffer, uint32_t buffer_size); ~~~ Optional. Callback to serialize the specified `component` to `buffer`. `buffer_size` will equal the `size` field of the `tm_component_persistence_i`. If the struct has dynamically sized data, you need to allocate buffers for that data using `tm_gamestate_api->reserve_persistent_buffer()` to ensure they are correctly serialized to the Gamestate. If you just want to use the component's entity context data for serialization, you can set `size` to `bytes`. If you do, there is no need to implement `serialize()`. !!! TODO: GAMESTATE-REVIEW Maybe `serialize()` and `deserialize()` should get pointers to the component, so they don't have to call `read_component()` or `write_component()`. That could let us do more efficient batch processing. #### `deserialize()` ~~~c void (*deserialize)(struct tm_entity_context_o *ctx, struct tm_gamestate_o *gamestate, tm_entity_t e, tm_component_type_t component, const void *buffer, uint32_t buffer_size); ~~~ Optional. Callback matching `serialize()` to deserialize the data from the `buffer` into the `component`. #### `compute_hash()` ~~~c uint64_t (*compute_hash)(struct tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component, const void *data, uint32_t size); ~~~ Optional. Callback to compute a hash of the component's current state. This is used to detect changes to the component when `manual_tracking` is set to *false*. If `compute_hash()` is not implemented, the hash will be computed as a hash of the component's data in the entity context. #### `compute_asset_hash()` ~~~c uint64_t (*compute_asset_hash)(struct tm_entity_context_o *ctx, struct tm_the_truth_o *tt, tm_component_type_t component, tm_tt_id_t asset); ~~~ Optional. Callback to compute the hash of a component asset. This is used to detect changes to the component when `manual_tracking` is set to *false*. If `compute_asset_hash()` is not implemented, the hash will be computed using `compute_hash()` if available, or using the hash of the component's data in the entity context. #### `loaded()` ~~~c void (*loaded)(struct tm_component_manager_o *manager, tm_entity_t e, void *data); ~~~ Optional. Custom Callback that is called when the component is loaded from the Gamestate. If not provided, `asset_reloaded()` or `asset_loaded()` of `tm_component_i` will be called if provided. #### `num_shared_members` ~~~c uint32_t num_shared_members; ~~~ The number of members that are shared by the Persistence and the Network Replication configuration. #### `shared_members` ~~~c struct tm_gamestate_member_t *shared_members; ~~~ The members that are shared by the Persistence and the network Replication config. Even if the number of bytes in the Gamestate allocated for a given component are the same, it may happen that the Persistence and the Network Replication want to look at the data differently. Nonetheless, the members that both share can be placed here for convenience.
### `struct tm_component_persistence_i`
#### `manual_tracking` ~~~c bool manual_tracking; ~~~ Optional. Controls how changes to the component's state are detected. If *true*, the user is responsible for manually keeping track of which components have changed and manually pushing those changes to the Gamestate. If *false*, the Entity Context will automatically detect changes by looping over all the Entities that have the component, call `compute_hash()` on them and compare the returned hash value with the last stored one to detect changes. Note that this is potentially a costly procedure, since it has to loop over all components. This loop is run when you call `propagate_persistence_changes_to_gamestate()`. #### `num_members` ~~~c uint32_t num_members; ~~~ Optional. Number of member fields in the serialized struct. This is only useful if `manual_tracking` is set to *true*, as otherwise the component `serialize()` and `deserialize()` callbacks of `tm_component_gamestate_representation_i` will be used. #### `members` ~~~c struct tm_gamestate_member_t *members; ~~~ Optional. Specifies what the individual members in the serialization struct are and at what offset they can be found. Only useful if `manual_tracking` is set to *True*, as otherwise the entity_context will use the `serialize()` and `deserialize()` callbacks of `tm_component_gamestate_representation_i`.
### `struct tm_member_network_replication_t`
~~~c typedef struct tm_member_network_replication_t { // Optional. Used to control how often the Gamestate should "check" whether this member has changed or not, by comparing the // entire binary data of the member. If changes are detected they will be pushed to the Gamestate immediately. // If set to 0, the struct will be checked every frame. If set to a negative value the struct won't ever be checked. double watch_timer; // Offset in the "runtime" data. Will be used to check if the member changed. uint32_t raw_component_offset; TM_PAD(4); // TODO(Leonardo): read, write callbacks } tm_member_network_replication_t; ~~~
### `struct tm_component_network_replication_i`
#### `watch_timer` ~~~c double watch_timer; ~~~ Optional. Used to control how often the Gamestate should "check" whether this struct has changed or not, by comparing the entire binary data of the struct. If changes are detected they will be pushed to the Gamestate immediately. If set to 0, the struct will be checked every frame. If set to a negative value the struct won't ever be checked. #### `num_members` ~~~c uint32_t num_members; ~~~ The number of members in the network gamestate configuration. #### `members` ~~~c struct tm_gamestate_member_t *members; ~~~ Optional. The members in the Network replication configuration. Must match `num_members` #### `member_replication` ~~~c tm_member_network_replication_t *member_replication; ~~~ Optional. Specifies how each member should be replicated. Must match `num_members`
### `struct tm_component_i`
Interface that defines a component. Components are registered into the context using this interface. #### `name` ~~~c const char *name; ~~~ Name of the component. The name of the component should be the same as the name of its asset type in The Truth. #### `bytes` ~~~c uint32_t bytes; ~~~ Bytes of POD data stored in the context for the component. #### `default_data` ~~~c const void *default_data; ~~~ Pointer to static data of size `bytes` that represents the default data for this component. If this is NULL, the default data is assumed to be `bytes` bytes of zeros. #### `manager` ~~~c tm_component_manager_o *manager; ~~~ Manager for the component. The manager will be used in the component callbacks below. The manager can be NULL for simple POD components. Components can share a manager. #### `components_created()` ~~~c void (*components_created)(tm_component_manager_o *manager); ~~~ Callback when all components have been created. This can be used to cache component indices in the manager. #### `load_asset()` ~~~c bool (*load_asset)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data, const struct tm_the_truth_o *tt, tm_tt_id_t asset); ~~~ Loads data from the Truth into the component. `data` is a pointer to `bytes` bytes of POD data for the component (it should be cast to the concrete component POD type). `asset` is the component's asset in The Truth. Note that we don't make any guarantees about the order in which `load_asset()` is called when an entity has multiple components. If you need to do initialization that depends on the existence of other components, you should do that in `asset_loaded()`. If `load_asset()` returns *false* it signifies that the component data has not changed and listeners to the component do not need to be notified of the change. (Note: A return value of *true* doesn't necessarily mean that the data *has* changed, it could also mean that this component hasn't implemented change detection.) #### `asset_loaded()` ~~~c void (*asset_loaded)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data); ~~~ Optional callback when all child entities of `e` have been loaded from The Truth. This can be used for post-load setup of the component. #### `asset_loaded_sort_order` ~~~c double asset_loaded_sort_order; ~~~ Double value that determines in which order asset-loaded functions of components are called (lower value are called first). #### `asset_reloaded()` ~~~c void (*asset_reloaded)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data); ~~~ Optional callback when all child entities of `e` have been loaded from The Truth as a result of a reload, because some of the component data changed. If `asset_reloaded()` not set by the component, `asset_loaded()` will be called instead in the case of a reload. #### `add()` ~~~c void (*add)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data, bool entity_is_being_created); ~~~ Optional callback when the component is added to an entity. If `entity_is_being_created` is *False* it means the component is being added "Afterwards" (with a call to `add_component()`) and is not part of the entity creation process. #### `remove()` ~~~c void (*remove)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data, bool entity_is_being_destroyed); ~~~ Optional callback when the component is removed from an entity. If `entity_is_being_destroyed` is *False* it means the component is being removed singularly (with a call to `remove_component()` and is not part of the entity deletion process. #### `destroy()` ~~~c void (*destroy)(tm_component_manager_o *manager); ~~~ Optional callback to destroy the component manager when the entity context is destroyed. #### `debug_draw()` ~~~c void (*debug_draw)(tm_component_manager_o *manager, tm_entity_t e[], const void *data[], uint32_t n, struct tm_primitive_drawer_context_t *primitive, const struct tm_camera_t *camera, tm_rect_t viewport); ~~~ Optional. Implements debug drawing for the component. The component will draw into the supplied drawing buffers. #### `debug_draw_settings` ~~~c tm_tt_id_t debug_draw_settings; ~~~ Optional. If non-zero, a Truth object that specifies settings for debug drawing. #### `gamestate_representation` ~~~c tm_component_gamestate_representation_i *gamestate_representation; ~~~ Optional. Specifies the Gamestate Representation of the component. #### `persistence` ~~~c tm_component_persistence_i *persistence; ~~~ Optional. Specifies the persistence settings for the component. If NULL, the component does not support persistence. Useless if `gamestate_representation` is NULL. #### `network_replication` ~~~c tm_component_network_replication_i *network_replication; ~~~ Optional. Specifies the Network Replication settings for the component. If NULL, the component does not support replication. Useless if `gamestate_representation` is NULL. #### `automatically_call_remove_when_destroying` ~~~c bool automatically_call_remove_when_destroying; ~~~ If *True*, `remove_component()` will be automatically called for each entity when the entity context is destroyed. #### `automatically_call_remove_when_reloading` ~~~c bool automatically_call_remove_when_reloading; ~~~ If *True*, `remove_component()` will be automatically called every time the component is reloaded inside a `propagate_asset_changes()` call, just before the reloading function is called.
### `tm_entity_create_component_i`
~~~c typedef void tm_entity_create_component_i(struct tm_entity_context_o *ctx); ~~~ Interface for creating a component manager (if the component uses one) and registering the component with the entity context.
### `tm_entity_create_component_i_version`
~~~c #define tm_entity_create_component_i_version TM_VERSION(3, 0, 0) ~~~ Current version of `tm_entity_create_component_i`.

Engines and systems

### `TM_MAX_COMPONENTS_FOR_ENGINE`
~~~c #define TM_MAX_COMPONENTS_FOR_ENGINE 32 ~~~ The maximum number of components that an engine can have.
### `struct tm_engine_update_array_t`
Represents contiguous arrays of entity and component data for an engine update function. ~~~c typedef struct tm_engine_update_array_t { tm_entity_t *entities; void *components[TM_MAX_COMPONENTS_FOR_ENGINE]; uint32_t component_bytes[TM_MAX_COMPONENTS_FOR_ENGINE]; uint32_t n; TM_PAD(4); } tm_engine_update_array_t; ~~~
### `struct tm_entity_blackboard_value_t`
Used to represent data on the entity context's "blackboard". The blackboard is a way of passing constant data to update engines without explicitly having to send it to each engine instance. It is typically used to pass global things such as "delta time". ~~~c typedef struct tm_entity_blackboard_value_t { tm_strhash_t id; union { double double_value; void *ptr_value; }; } tm_entity_blackboard_value_t; ~~~
### `struct tm_engine_update_set_t`
Represents a set of data for an engine update, formed from one or more contiguous arrays. ~~~c typedef struct tm_engine_update_set_t { const struct tm_engine_i *engine; uint32_t total_entities; TM_PAD(4); const tm_entity_blackboard_value_t *blackboard_start; const tm_entity_blackboard_value_t *blackboard_end; // number of entity types (also known as archetypes) uint32_t num_arrays; TM_PAD(4); tm_engine_update_array_t arrays[0]; } tm_engine_update_set_t; ~~~
### `tm_engine_o`
~~~c typedef struct tm_engine_o tm_engine_o; ~~~
### `TM_MAX_DEPENDENCIES_FOR_ENGINE`
Maximum number of dependencies an engine can have. ~~~c enum { TM_MAX_DEPENDENCIES_FOR_ENGINE = 16 }; ~~~
### `TM_PHASE__ANIMATION`
~~~c #define TM_PHASE__ANIMATION TM_STATIC_HASH("TM_PHASE__ANIMATION", 0x61707ef35caceb1eULL) ~~~ Phase for animation jobs. Predefined phases that can be used for `tm_engine_system_common_i->phase` and specified in the `tm_engine_system_common_i->before_me` and `tm_engine_system_common_i->after_me` arrays. Note that phases are just string hashes and you can extend the systems with more phases if desired.
### `TM_PHASE__PHYSICS`
~~~c #define TM_PHASE__PHYSICS TM_STATIC_HASH("TM_PHASE__PHYSICS", 0x89d3a3f3c6ac93b6ULL) ~~~ Phase for physics jobs.
### `TM_PHASE__GRAPH`
~~~c #define TM_PHASE__GRAPH TM_STATIC_HASH("TM_PHASE__GRAPH", 0x6e300373bbd21b89ULL) ~~~ Phase for the visual scripting graph update.
### `TM_PHASE__CAMERA`
~~~c #define TM_PHASE__CAMERA TM_STATIC_HASH("TM_PHASE__CAMERA", 0x45e32640d97fcf85ULL) ~~~ Phase for camera jobs.
### `TM_PHASE__RENDER`
~~~c #define TM_PHASE__RENDER TM_STATIC_HASH("TM_PHASE__RENDER", 0x8421392b8cf59ebaULL) ~~~ Phase for render jobs.
### `struct tm_engine_system_common_i`
Common fields for `tm_engine_i` and `tm_entity_system_i`. #### `ui_name` ~~~c const char *ui_name; ~~~ Name of the engine/system. This is localized for display. #### `hash` ~~~c tm_strhash_t hash; ~~~ Unique string hash identifying this engine/system. This is used for scheduling the engine/system with respect to other engines and systems, using the `before_me` and `after_me` fields. #### `disabled` ~~~c bool disabled; ~~~ If true, this engine/system is currently disabled from running. #### `exclusive` ~~~c bool exclusive; ~~~ If *true*, this engine/system is considered "exclusive". It will not run in parallel with any other systems or engines in the entity context. If *false*, `components` and `writes` will be used to determine parallelism. #### `num_components` ~~~c uint32_t num_components; ~~~ Number of components used by this engine/system. #### `components` ~~~c tm_component_type_t components[TM_MAX_COMPONENTS_FOR_ENGINE]; ~~~ List of components. For engines, the `update()` function will receive component data in the order that it is listed here. For systems, this is just used to determine parallelism. #### `writes` ~~~c bool writes[TM_MAX_COMPONENTS_FOR_ENGINE]; ~~~ Flag for each component that indicates whether the engine/system writes to the component or not. Used for job synchronization between engines/systems. #### `before_me` ~~~c tm_strhash_t before_me[TM_MAX_DEPENDENCIES_FOR_ENGINE]; ~~~ A list of engines/systems that should be scheduled before this engine. Note that setting `before_me` just controls the order the engines gets scheduled. It does not explicitly wait for the listed engines to *finish*. If the `writes` field allows the two engines to run simultaneously, they will still do so. #### `after_me` ~~~c tm_strhash_t after_me[TM_MAX_DEPENDENCIES_FOR_ENGINE]; ~~~ A list of engines/systems that should be scheduled after this engine. #### `phase` ~~~c tm_strhash_t phase; ~~~ Specifies the *phase* of this item. Phases can be used to wait for a group of items using the `before_me` and `after_me` arrays. For example, if you add `TM_PHASE__ANIMATION` to `before_me`, that means that all items that have `phase` set to `TM_PHASE__ANIMATION` must be scheduled before this job.
### `struct tm_engine_i`
Interface for *engines*. An *engine* is an update that runs on entities that have certain components (listed in the `components` list). Since entity data is sorted by entity type (which components an entity has), engines can iterate very quickly over component data (the data is sent directly to the `update()` function). #### `TM_INHERITS()` ~~~c TM_INHERITS(struct tm_engine_system_common_i); ~~~ #### `inst` ~~~c tm_engine_o *inst; ~~~ Callback object. #### `update()` ~~~c void (*update)(tm_engine_o *inst, tm_engine_update_set_t *data, struct tm_entity_commands_o *commands); ~~~ Callback function for engine update. #### `num_excluded` ~~~c uint32_t num_excluded; ~~~ Number of component types to be excluded. The `update()` will run on entities that have all the components in the `components` list and none of the components in the `excluded` list. If you need more advanced criteria than this to determine whether the engine should run or not, for a specific entity type, you can implement the `filter()` callback. #### `excluded` ~~~c tm_component_type_t excluded[TM_MAX_COMPONENTS_FOR_ENGINE]; ~~~ List of component types that this engine will not run on. #### `filter()` ~~~c bool (*filter)(tm_engine_o *inst, const tm_component_type_t *components, uint32_t num_components, const tm_component_mask_t *mask); ~~~ Optional. If non-NULL, specifies a filter function that is called for each entity type (as represented by its component mask) to determine if the engine should run on that entity type. If no `filter()` function is supplied and no `excludes[]` flags are set, the update will run on entity types that have all the components in the `components` array. If some `excludes[]` flags are set, the engine will run on all entity types that *do not* have any of the components whose `excludes[]` flags are set, but have all the other components in the `components` array. If a `filter()` is set, it will be run to determine if the engine runs on that entity type or not. Note especially that in this case, the contents of the `excludes[]` array is ignored. The `filter()` callback allows you to specify more complicated criteria than pure exclusion, such as: *"run on all types that have component A or B, but not C"*. `components` is the list of components that will be passed to the update function and `mask` is the component mask of the entity type that we are testing. Should return *true* if the engine should run for the entity type and *false* otherwise.
### `tm_entity_system_o`
~~~c typedef struct tm_entity_system_o tm_entity_system_o; ~~~
### `struct tm_entity_system_i`
Interface for an *entity system*. An entity system is similar to an *engine*, but unlike an engine, the entity system is not sent any component data, so if it wants to access that data it has to call `write_component()` which will be a lot slower and less cache friendly. *Entity Systems* are useful when the data in the component is just a pointer into some external system. (This is the case for example for PhysX components). In this case, this external system is assumed to store its data in a cache friendly order, which means we actually do *not* want to iterate over the entities in the order they are stored in the entity system, since this would cause pointer chasing in the external system. Instead, we just want to send a single `update()` to the external system and it will process the entities in its own (cache-friendly) order. #### `TM_INHERITS()` ~~~c TM_INHERITS(struct tm_engine_system_common_i); ~~~ #### `inst` ~~~c tm_entity_system_o *inst; ~~~ Callback object. #### `inited` ~~~c bool inited; ~~~ Will be set to true after `init` callback after first run of this system (which also means `init()` will have been run, if it is implemented. #### `init()` ~~~c void (*init)(struct tm_entity_context_o *ctx, tm_entity_system_o *inst, struct tm_entity_commands_o *commands); ~~~ Optional. Callback for init of system, called once, before the first call to `update()` #### `update()` ~~~c void (*update)(struct tm_entity_context_o *ctx, tm_entity_system_o *inst, struct tm_entity_commands_o *commands); ~~~ Optional. Callback function for system update. #### `shutdown()` ~~~c void (*shutdown)(struct tm_entity_context_o *ctx, tm_entity_system_o *inst, struct tm_entity_commands_o *commands); ~~~ Optional. Callback for shutdown of system, called once just before entity context shuts down, or if the system has been inited but is about to be removed. #### `hot_reload()` ~~~c void (*hot_reload)(struct tm_entity_context_o *ctx, tm_entity_system_o *inst, struct tm_entity_commands_o *commands); ~~~ Optional. Called after a code hot reload has happened.
### `tm_entity_register_engines_i`
~~~c typedef void tm_entity_register_engines_i(struct tm_entity_context_o *ctx); ~~~ Callback for registering engines and systems with entity contexts. These callbacks are registered with `tm_add_or_remove_implementation()` using either `tm_entity_register_engines_simulation_i` or `tm_entity_register_engines_editor_i` to run automatically in the "Simulate" or "Preview" tabs.
### `tm_entity_register_engines_simulation_i`
~~~c typedef tm_entity_register_engines_i tm_entity_register_engines_simulation_i; ~~~ Used to register a `tm_entity_register_engines_i` that should run in simulation mode with `tm_add_or_remove_implementation()`.
### `tm_entity_register_engines_simulation_i_version`
~~~c #define tm_entity_register_engines_simulation_i_version TM_VERSION(1, 0, 0) ~~~
### `tm_entity_register_engines_editor_i`
~~~c typedef tm_entity_register_engines_i tm_entity_register_engines_editor_i; ~~~ Used to register a `tm_entity_register_engines_i` that should run in editor mode with `tm_add_or_remove_implementation()`.
### `tm_entity_register_engines_editor_i_version`
~~~c #define tm_entity_register_engines_editor_i_version TM_VERSION(1, 0, 0) ~~~

Blackboard

### `TM_ENTITY_BB__SIMULATION_SPEED`
~~~c #define TM_ENTITY_BB__SIMULATION_SPEED TM_STATIC_HASH("tm_simulation_speed", 0x5b23afbbfdabc0cULL) ~~~ Speed that the simulation is running at. Defaults to 1.0 for normal speed.
### `TM_ENTITY_BB__DELTA_TIME`
~~~c #define TM_ENTITY_BB__DELTA_TIME TM_STATIC_HASH("tm_delta_time", 0x5e57dbf636f8eacbULL) ~~~ Blackboard item representing the simulation delta time of the current frame.
### `TM_ENTITY_BB__TIME`
~~~c #define TM_ENTITY_BB__TIME TM_STATIC_HASH("tm_time", 0x6a30b071f871aa9dULL) ~~~ Blackboard item representing the total elapsed time in the simulation.
### `TM_ENTITY_BB__WALL_DELTA_TIME`
~~~c #define TM_ENTITY_BB__WALL_DELTA_TIME TM_STATIC_HASH("tm_wall_delta_time", 0x65f477113ad0164aULL) ~~~ Blackboard item representing the wall delta time of the current frame. (Wall delta time is not affected by the simulation being paused or run in slow motion.)
### `TM_ENTITY_BB__WALL_TIME`
~~~c #define TM_ENTITY_BB__WALL_TIME TM_STATIC_HASH("tm_wall_time", 0x99071b8209e8c2dbULL) ~~~ Blackboard item representing the total elapsed wall time in the simulation.
### `TM_ENTITY_BB__UI`
~~~c #define TM_ENTITY_BB__UI TM_STATIC_HASH("tm_ui", 0x8bf15b8ddd21ddf8ULL) ~~~ Blackboard items for the current UI. The difference between `TM_ENTITY_BB__UI_RECT` and `TM_ENTITY_BB__UI_VIEWPORT_RECT` is that the later contains the offset of tab's viewport !!! note: TODO Should these be passed to the graph component directly instead of on the blackboard?
### `TM_ENTITY_BB__UI_STYLE`
~~~c #define TM_ENTITY_BB__UI_STYLE TM_STATIC_HASH("tm_ui_style", 0x6e807ddd0bc1ce44ULL) ~~~
### `TM_ENTITY_BB__UI_RECT`
~~~c #define TM_ENTITY_BB__UI_RECT TM_STATIC_HASH("tm_ui_rect", 0x826d34ad4961b3f8ULL) ~~~
### `TM_ENTITY_BB__UI_VIEWPORT_RECT`
~~~c #define TM_ENTITY_BB__UI_VIEWPORT_RECT TM_STATIC_HASH("tm_ui_viewport_rect", 0xef89b17d09fa6c80ULL) ~~~
### `TM_ENTITY_BB__UI_SCALE_FACTOR`
~~~c #define TM_ENTITY_BB__UI_SCALE_FACTOR TM_STATIC_HASH("tm_ui_scale_factor", 0xbb4580daf36dbfa7ULL) ~~~
### `TM_ENTITY_BB__WINDOW`
~~~c #define TM_ENTITY_BB__WINDOW TM_STATIC_HASH("tm_window", 0x681e7f7cb09013bbULL) ~~~
### `TM_ENTITY_BB__CAMERA`
~~~c #define TM_ENTITY_BB__CAMERA TM_STATIC_HASH("tm_camera", 0x2682ee84e32ed18ULL) ~~~ Blackboard items for the current camera.
### `TM_ENTITY_BB__CAMERA_TRANSFORM`
~~~c #define TM_ENTITY_BB__CAMERA_TRANSFORM TM_STATIC_HASH("tm_camera_transform", 0xa927612ef42b851aULL) ~~~
### `TM_ENTITY_BB__EDITOR`
~~~c #define TM_ENTITY_BB__EDITOR TM_STATIC_HASH("tm_editor", 0x6ff26491644e31b1ULL) ~~~ Blackboard item that indicates that we are running in *Editor* mode. This may disable some components and/or simulation engines.
### `TM_ENTITY_BB__ASSET_ROOT`
~~~c #define TM_ENTITY_BB__ASSET_ROOT TM_STATIC_HASH("tm_asset_root", 0xac77a365b39e6253ULL) ~~~ Blackboard item for accessing the asset root.
### `TM_ENTITY_BB__VIEWER`
~~~c #define TM_ENTITY_BB__VIEWER TM_STATIC_HASH("tm_viewer_o", 0x855653f2cdd58a65ULL) ~~~ Blackboard item for accessing the `tm_viewer_o` that is viewing the scene.

Visual entity picker

### `enum tm_entity_visual_picker_state`
~~~c enum tm_entity_visual_picker_state { TM_ENTITY_VISUAL_PICKER_STATE__NONE, TM_ENTITY_VISUAL_PICKER_STATE__PICKING, TM_ENTITY_VISUAL_PICKER_STATE__DONE, }; ~~~
### `TM_ENTITY_VISUAL_PICKER_RESULT_NUM_ASSSETS_MENU_PICK`
~~~c #define TM_ENTITY_VISUAL_PICKER_RESULT_NUM_ASSSETS_MENU_PICK 16 ~~~
### `struct tm_entity_visual_picker_result_t`
~~~c typedef struct tm_entity_visual_picker_result_t { // Non-zero if a picking operation is in flight or done. enum tm_entity_visual_picker_state state; TM_PAD(4); tm_tt_id_t asset_fast_pick; tm_tt_id_t assets_menu_pick[TM_ENTITY_VISUAL_PICKER_RESULT_NUM_ASSSETS_MENU_PICK]; } tm_entity_visual_picker_result_t; ~~~
### `tm_entity_visual_picker_o`
~~~c typedef struct tm_entity_visual_picker_o tm_entity_visual_picker_o; ~~~
### `struct tm_entity_visual_picker_i`
For picking entities visually using an entity picker. I.e. for clicking within a 3D viewport and returning which asset was picked. #### `inst` ~~~c tm_entity_visual_picker_o *inst; ~~~ Passed to `pick()` by the caller. #### `pick()` ~~~c tm_entity_visual_picker_result_t (*pick)(tm_entity_visual_picker_o *inst, struct tm_ui_o *ui, const struct tm_ui_style_t *uistyle, tm_tt_id_t relative_to, uint64_t active_id); ~~~ Can be called by any active entity picker. The implementation can then check if the mouse is inside a certain rect (such as a tab rect) and then check for mouse clicks and for example do some GPU based picking. `active_id` is the UI ID of the actual picker control. This can be cached in the implementation to track if the picker lost while a GPU picking operation was in flight. Returns an object of type `tm_entity_visual_picker_result_t`. `state` within the result is non-zero if any picking is in flight (some GPU picking operations go across frames) or if there is a picking result.
### `tm_entity_visual_picker_i_version`
~~~c #define tm_entity_visual_picker_i_version TM_VERSION(1, 0, 0) ~~~

API

### `enum tm_entity_create_components`
~~~c enum tm_entity_create_components { // Creates a "naked" context. Any components you want must be explicitly created and registered // manually with `register_component`. TM_ENTITY_CREATE_COMPONENTS_NONE, // Creates a context that includes all the components registered with the // [[tm_entity_create_component_i]] interface. TM_ENTITY_CREATE_COMPONENTS_ALL, // Creates a context that includes the components suitable for editor use (i.e. no simulation // components). This is achieved by setting the [[TM_ENTITY_BB__EDITOR]] flag before calling all // [[tm_entity_create_component_i]] interfaces. Interfaces can check for this flag // being set and avoid creating the components if set. TM_ENTITY_CREATE_COMPONENTS_EDITOR, }; ~~~
### `struct tm_entity_listener_i`
Defines an interface for components that can listen to changes to other components. #### `man` ~~~c tm_component_manager_o *man; ~~~ Manager to notify. #### `notify_e` ~~~c tm_entity_t notify_e; ~~~ Entity to notify. #### `notify_c` ~~~c tm_component_type_t notify_c; ~~~ Component to notify; #### `notify()` ~~~c void (*notify)(tm_entity_context_o *ctx, tm_component_manager_o *man, tm_entity_t e, void *c, tm_entity_t notify_e, void *notify_c); ~~~ Callback to notify the component `notify_c` of the entity `notify_e` that the component `c` of the entity `e` has changed.
### `struct tm_entity_event_listener_i`
Interface for notifying listeners about events that happen to entities (via `listen_event()`). #### `inst` ~~~c void *inst; ~~~ Instance of object to notify. #### `user_data` ~~~c void *user_data; ~~~ User data that will be supplied to the callback function. #### `notify()` ~~~c void (*notify)(void *inst, tm_entity_context_o *ctx, tm_strhash_t event, tm_entity_t e, const void *event_data, uint32_t event_data_bytes, void *user_data); ~~~ Called to notify the listener about an event. `inst` and `user_data` come from `tm_entity_event_listener_i`. `event` is the event type (hashed string). `e` is the entity that the event happened to and `event_data` contains (event specific) data for the event.
### `struct tm_entity_array_t`
Represents a contiguous array of entities. ~~~c typedef struct tm_entity_array_t { tm_entity_t *entities; uint32_t n; TM_PAD(4); } tm_entity_array_t; ~~~
### `struct tm_entity_set_t`
Represents a set of entities formed by one or more contiguous arrays. ~~~c typedef struct tm_entity_set_t { uint32_t total_entities; uint32_t num_arrays; tm_entity_array_t arrays[0]; } tm_entity_set_t; ~~~
### `struct tm_entity_api`
!!! note: TODO How should we reason about threading for listening callbacks? a. Callbacks must be thread-safe (queue events up for later processing). b. Callbacks can do anything (must be called on "main thread"). c. Callbacks must "declare" their thread safety somehow, so we can reason about it...

#### `create_context()` ~~~c tm_entity_context_o *(*create_context)(struct tm_allocator_i *a, struct tm_the_truth_o *tt, enum tm_entity_create_components create_components, struct tm_gamestate_o *gamestate); ~~~ Creates a new simulation context where entities live. #### `destroy_context()` ~~~c void (*destroy_context)(tm_entity_context_o *ctx); ~~~ Destroys a simulation context created by `create_context()`. #### `set_debug_name()` ~~~c void (*set_debug_name)(tm_entity_context_o *ctx, const char *debug_name); ~~~ Can be used to set a debug name for the current entity context. Takes over the memory ownership. #### `debug_name()` ~~~c const char *(*debug_name)(tm_entity_context_o *ctx, struct tm_temp_allocator_i *ta); ~~~ Can be used to get the debug name. #### `create_components()` ~~~c void (*create_components)(struct tm_entity_context_o *ctx, enum tm_entity_create_components create_components); ~~~ In case where `create_context()` was called specifying `TM_ENTITY_CREATE_COMPONENTS_NONE`, registers the components. Otherwise is a NOP. This is useful because it allows the user to disable components by calling `disable_component()` inbetween the call to `create_context()` and `create_components()` #### `register_component()` ~~~c tm_component_type_t (*register_component)(tm_entity_context_o *ctx, const struct tm_component_i *com); ~~~ Registers a component with the context. #### `disable_component()` ~~~c void (*disable_component)(tm_entity_context_o *ctx, tm_strhash_t component_hash); ~~~ Disables the specified component. `disable_component()` only works if called before the components are created in the entity context. So to use it, you must take the following steps to create the entity context: - Create the entity context without components by calling `create_context()` with `TM_ENTITY_CREATE_COMPONENTS_NONE`. - Disable any undesired components by calling `disable_component()`. - Create the remaining components by calling `create_components()` witn `TM_ENTITY_CREATE_COMPONENTS_ALL`. #### `num_components()` ~~~c uint32_t (*num_components)(tm_entity_context_o *ctx); ~~~ Returns the number of registered components. #### `component()` ~~~c const struct tm_component_i *(*component)(tm_entity_context_o *ctx, tm_component_type_t component_type); ~~~ Returns data about a registered component. #### `register_engine()` ~~~c void (*register_engine)(tm_entity_context_o *ctx, const tm_engine_i *engine); ~~~ Registers an engine with the context. !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects. If needed in a System/Engine please make use of the `tm_entity_commands_api->register_system()`. #### `remove_engine()` ~~~c void (*remove_engine)(tm_entity_context_o *ctx, tm_strhash_t engine_hash); ~~~ Removes the specified engine from the context. If the engine wasn't registered in the context, this is a NOP. !!! note: Information It will be executed at the end of the frame if this is called from within the ECS. #### `registered_engines()` ~~~c tm_engine_i *(*registered_engines)(tm_entity_context_o *ctx, uint32_t *count); ~~~ Returns all registered engines. #### `register_system()` ~~~c void (*register_system)(tm_entity_context_o *ctx, const tm_entity_system_i *system); ~~~ Registers an system with the context. !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects (such as invalidate all system/engine). If needed in a System/Engine please make use of the `tm_entity_commands_api->register_system()`. #### `remove_system()` ~~~c void (*remove_system)(tm_entity_context_o *ctx, tm_strhash_t system_hash); ~~~ Removes the specified system from the context. If the system wasn't registered in the context, this is a NOP. !!! note: Information It will be executed at the end of the frame if this is called from within the ECS. #### `registered_systems()` ~~~c tm_entity_system_i *(*registered_systems)(tm_entity_context_o *ctx, uint32_t *count); ~~~ Returns all registered systems that are registered at this point in time. #### `the_truth()` ~~~c struct tm_the_truth_o *(*the_truth)(tm_entity_context_o *ctx); ~~~ Returns The Truth object that the context was created with. #### `create_child_allocator()` ~~~c void (*create_child_allocator)(tm_entity_context_o *ctx, const char *name, struct tm_allocator_i *a); ~~~ Creates a child allocator for the context. This is used by component owners to create memory scopes for their data. #### `destroy_child_allocator()` ~~~c void (*destroy_child_allocator)(tm_entity_context_o *ctx, struct tm_allocator_i *a); ~~~ Destroys a child allocator created by `create_child_allocator()`.

#### `create_entity()` ~~~c tm_entity_t (*create_entity)(tm_entity_context_o *ctx); ~~~ Creates a new entity in the context and returns its ID. Note that entity ID's are only guaranteed to be unique within a specific context. #### `batch_create_entity()` ~~~c void (*batch_create_entity)(tm_entity_context_o *ctx, tm_entity_t *es, uint32_t n); ~~~ #### `create_entity_from_mask()` ~~~c tm_entity_t (*create_entity_from_mask)(tm_entity_context_o *ctx, const tm_component_mask_t *mask); ~~~ Creates an entity matching the specified component mask. !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects. If needed in a System/Engine please make use of the `tm_entity_commands_api->create_entity_from_mask()`. #### `batch_create_entity_from_mask()` ~~~c void (*batch_create_entity_from_mask)(tm_entity_context_o *ctx, const tm_component_mask_t *mask, tm_entity_t *es, uint32_t n); ~~~ #### `create_entity_from_asset()` ~~~c tm_entity_t (*create_entity_from_asset)(tm_entity_context_o *ctx, tm_tt_id_t asset); ~~~ Creates an entity based on an entity asset in The Truth. Components and children of the asset will be automatically created. !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects. If needed in a System/Engine please make use of the `tm_entity_commands_api->create_entity_from_asset()`. #### `batch_create_entity_from_asset()` ~~~c void (*batch_create_entity_from_asset)(tm_entity_context_o *ctx, tm_tt_id_t asset, tm_entity_t *es, uint32_t n); ~~~ #### `create_entity_from_asset_with_world_transform()` ~~~c tm_entity_t (*create_entity_from_asset_with_world_transform)(tm_entity_context_o *ctx, tm_tt_id_t asset, tm_transform_t t); ~~~ As `create_entity_from_asset()`, but creates the entity at the specified world transform `t`. #### `batch_create_entity_from_asset_with_world_transforms()` ~~~c void (*batch_create_entity_from_asset_with_world_transforms)(tm_entity_context_o *ctx, tm_tt_id_t asset, const tm_transform_t *ts, tm_entity_t *es, uint32_t n); ~~~ #### `create_network_entity()` ~~~c tm_entity_t (*create_network_entity)(tm_entity_context_o *ctx, tm_tt_id_t asset, bool is_proxy, uint64_t match_key); ~~~ Same as `create_entity_from_asset()`, but let the Gamestate know that this specific entity was originated from the `network_event_name` event triggered by the `network_event_entity` entity. If `is_proxy` is *true*, create the entity as a fake entity that will later be matched when a remote entity loaded from the Gamestate has the same `key`. #### `destroy_entity()` ~~~c void (*destroy_entity)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Destroys an entity created by create_entity(). !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects. If needed in a System/Engine please make use of the `tm_entity_commands_api->destroy_entity()`. #### `batch_destroy_entity()` ~~~c void (*batch_destroy_entity)(tm_entity_context_o *ctx, const tm_entity_t *es, uint32_t n); ~~~ #### `queue_destroy_entities()` ~~~c void (*queue_destroy_entities)(tm_entity_context_o *ctx, const tm_entity_t *es, uint32_t n); ~~~ Queues entities to be destroyed during the next entity context `update()`. This is useful when you want to destroy an entity from within a component that is owned by entity, since destroying it immediately would destroy the data the component is using. Note that entities queued for destruction will continue to respond *true* to `is_alive()` queries until they're *actually* destroyed. #### `clear_world()` ~~~c void (*clear_world)(tm_entity_context_o *ctx); ~~~ Destroys all the entities in the context and clears up any queued command. !!! note: Usage within a System or Engine This function should not be used within a Engine or System, since it is invoked directly and might cause changes with unwanted side effects. If needed in a System/Engine please make use of the `tm_entity_commands_api->clear_world()`. #### `is_alive()` ~~~c bool (*is_alive)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Returns *true* if the entity is alive. Entities are weakly referenced and the `is_alive()` function can be used to check if a previously created entity is still alive.

#### `num_entities()` ~~~c uint32_t (*num_entities)(tm_entity_context_o *ctx); ~~~ Returns the total number of entities in the context. #### `entities_matching()` ~~~c tm_entity_set_t *(*entities_matching)(tm_entity_context_o *ctx, const tm_component_mask_t *required, const tm_component_mask_t *forbidden, struct tm_temp_allocator_i *ta); ~~~ Returns the set of all entities that have all the components in the `required` mask (They may also have additional components.) , but none of the components in the `forbidden` mask. The set is allocated using the temp allocator. #### `flatten_set()` ~~~c void (*flatten_set)(tm_entity_t *entities, const tm_entity_set_t *set); ~~~ Flattens an entity set into a flat list of entities. The `entities` array must have enough room for `set->total_entities`. #### `asset_parent()` ~~~c tm_entity_t (*asset_parent)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Returns the parent in the asset hierarchy of the entity `e` when spawned as a child entity. #### `asset()` ~~~c tm_tt_id_t (*asset)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Returns the asset used to create the specified entity. #### `find_first_entity_from_asset()` ~~~c tm_entity_t (*find_first_entity_from_asset)(tm_entity_context_o *ctx, tm_tt_id_t asset); ~~~ Returns the first entity found created from the specified asset. Be careful about using this function when the same asset might be instanced multiple times in the entity context. #### `find_entities_from_assets()` ~~~c tm_entity_t *(*find_entities_from_assets)(tm_entity_context_o *ctx, const tm_tt_id_t *assets, uint32_t num_assets, struct tm_temp_allocator_i *ta); ~~~ Returns a `carray.inl` containing all the entities created from the list of `assets`, allocated with `ta`. #### `resolve_asset_reference()` ~~~c tm_entity_t (*resolve_asset_reference)(tm_entity_context_o *ctx, tm_entity_t e, tm_tt_id_t asset); ~~~ Resolves a reference to the `asset` in the context of the entity `e`. If the reference can't be resolved, the nil entity is returned. !!! note: TODO Using this function could be slow when a lot of asset references need to be resolved. We should consider using dynamic programming to cache the lookup structures for faster resolve. #### `resolve_asset_path()` ~~~c tm_entity_t (*resolve_asset_path)(tm_entity_context_o *ctx, tm_entity_t e, const char *path); ~~~ Given a reference entity `e` and a `path` of entity names separated by slashes, returns the entity at the path relative to the reference entity `e`. In the path `..` can be used to refer to the parent entity and `.` to the entity itself.

#### `lookup_component_type()` ~~~c tm_component_type_t (*lookup_component_type)(tm_entity_context_o *ctx, tm_strhash_t name_hash); ~~~ Looks up a component by name and returns a handle to its type. Returns `TM_NO_COMPONENT_TYPE` if the component doesn't exist. #### `component_manager()` ~~~c tm_component_manager_o *(*component_manager)(tm_entity_context_o *ctx, tm_component_type_t component_type); ~~~ Returns the manager for the specified component, if any. #### `component_manager_by_hash()` ~~~c tm_component_manager_o *(*component_manager_by_hash)(tm_entity_context_o *ctx, tm_strhash_t name_hash); ~~~ Directly gets the manager using the component hashes that the entity type stores, without havig to call the lookup function. #### `create_component_mask()` ~~~c tm_component_mask_t (*create_component_mask)(const tm_component_type_t *components, uint32_t n); ~~~ Creates a component mask from the specified list of components. #### `component_mask()` ~~~c const tm_component_mask_t *(*component_mask)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Returns the component mask of the entity. #### `add_component()` ~~~c void *(*add_component)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component); ~~~ Adds the specified component to the entity and returns its POD data. You should cast the returned pointer to the concrete POD data type for the component. If the entity already has the component, this function just returns a pointer to the data. #### `has_component()` ~~~c bool (*has_component)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t c); ~~~ Returns whether the specified entity `e` has the component `c`. #### `read_component()` ~~~c const void *(*read_component)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component); ~~~ Gets the POD data for the specific component in the entity. If the entity doesn't have the specified component, returns NULL. #### `read_component_by_hash()` ~~~c const void *(*read_component_by_hash)(tm_entity_context_o *ctx, tm_entity_t e, tm_strhash_t name_hash); ~~~ Directly gets the component using the component hashes that the entity type stores, without having to call the lookup function. #### `write_component()` ~~~c void *(*write_component)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component); ~~~ Returns a writeable pointer to the component data, or NULL if the entity doesn't have the speficied component. #### `write_component_by_hash()` ~~~c void *(*write_component_by_hash)(tm_entity_context_o *ctx, tm_entity_t e, tm_strhash_t name_hash); ~~~ Directly get the writeable pointer unsing the component hash, without having to call the lookup function. #### `remove_component()` ~~~c void (*remove_component)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component); ~~~ Removes the specified component from the entity. If the entity doesn't have the component, this is a NOP.

#### `propagate_asset_changes()` ~~~c void (*propagate_asset_changes)(tm_entity_context_o *ctx); ~~~ Propagates the changes that have been made to assets in The Truth into the context. I.e., every entity created from an asset that has changed will be updated with the asset changes. #### `propagate_listen_to()` ~~~c void (*propagate_listen_to)(tm_entity_context_o *ctx, tm_entity_t e, tm_tt_id_t object); ~~~ In addition to changes to its own asset, the entity `e` will also listen to changes to the specified object and reload itself if that object changes. This can be used to listen to changes to referenced objects (not subobjects). #### `mark_asset_as_propagated()` ~~~c void (*mark_asset_as_propagated)(tm_entity_context_o *ctx, tm_entity_t e, uint32_t old_version, uint32_t new_version); ~~~ Set the version of the asset of specified entity `e` to be `version` (if the current version held in the context is equal to to `old_version`), so that when `propagate_asset_changes()` is called the components are not reloaded again from The Truth. Useful when you are using a "runtime" value to drive The Truth value and you don't want the value to be overriden when `propagate_asset_changes()` is called.

#### `update()` ~~~c void (*update)(tm_entity_context_o *ctx); ~~~ Runs all registered engines and systems. Engines run as jobs through the job system. The jobs are queued with the job system in the order they are registered, and each job waits on the last job that wrote the components it uses. Consider a setup with four engines A, B, C, D, E, F and three components 1, 2, 3 where the components read (r) and written (w) by each engine is: A w1, B w2, C r1w2, D r1w3, E r12, F r12 With this setup the scheduling will work like this: * A queued (no wait, since 1 hasn't been written yet) * B queued (no wait, since 2 hasn't been written yet) * C queued (waits on A & B, because A wrote 1 and B wrote 2) * D queued (no wait, since 3 hasn't been written yet) * E queued (waits on A & C, because A wrote 1 and C wrote 2) * F queued (waits on A & C, because A wrote 1 and C wrote 2) #### `run_engine()` ~~~c void (*run_engine)(tm_entity_context_o *ctx, const struct tm_engine_i *engine); ~~~ Runs the specified engine on the matching entities. #### `run_engine_with_commands()` ~~~c void (*run_engine_with_commands)(tm_entity_context_o *ctx, const struct tm_engine_i *engine, struct tm_entity_commands_o *commands); ~~~ The same functionality as `run_engine()` just that you need to pass commands. #### `flush_command_queues()` ~~~c void (*flush_command_queues)(tm_entity_context_o *ctx); ~~~ Flushes all command queues in the entity system. Must be called at a safe synchronization point.

#### `set_blackboard_double()` ~~~c void (*set_blackboard_double)(tm_entity_context_o *ctx, tm_strhash_t id, double value); ~~~ Sets the blackboard value identified by `id` to `value`. This function is thread-safe and can be called from any thread. The blackboard is used to hold values that can be used by entity engines without having to be explicitly passed around. A typical use is to pass the delta time. #### `set_blackboard_ptr()` ~~~c void (*set_blackboard_ptr)(tm_entity_context_o *ctx, tm_strhash_t id, void *value); ~~~ Sets the blackboard value identified by `id` to `value`. Thread-safe. #### `has_blackboard()` ~~~c bool (*has_blackboard)(tm_entity_context_o *ctx, tm_strhash_t id); ~~~ True if there is a blackboard item with `id`. Thread-safe. #### `get_blackboard_double()` ~~~c double (*get_blackboard_double)(tm_entity_context_o *ctx, tm_strhash_t id, double def); ~~~ Returns the value of the specified blackboard item. If the values hasn't been set, the returned value is `def`. Thread-safe. #### `get_blackboard_ptr()` ~~~c void *(*get_blackboard_ptr)(tm_entity_context_o *ctx, tm_strhash_t id); ~~~ Returns the value of the specified blackboard item. If the values hasn't been set, the returned value is `NULL`. Thread-safe.

#### `listen()` ~~~c void (*listen)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t c, const tm_entity_listener_i *listener); ~~~ Registers a listener for changes to component `c` of entity `e`. This allows components to react immediately to changes to other components. Immediate reaction is an alternative to the batch processing that can be done through the engine interface. As a developer of a system you have to decide which approach works for you. #### `unlisten()` ~~~c void (*unlisten)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t c, const tm_entity_listener_i *listener); ~~~ Removes a listener registered with `listen()`. #### `notify()` ~~~c void (*notify)(tm_entity_context_o *ctx, tm_component_type_t component_type, const tm_entity_t *entities, uint32_t num_entities); ~~~ Records that the `component` has changed for the specified list of entities. If there are listeners to the change, those listeners will be called immediately. #### `listen_event()` ~~~c void (*listen_event)(tm_entity_context_o *ctx, tm_entity_t e, tm_strhash_t event, const tm_entity_event_listener_i *listener); ~~~ Registers a listener for events of `type` (a string hash) that happens to entity `e`. When an event of the specified type is triggered for the entity (with `notify_event()`, the listener is called). This is used as a generic system for passing entity events to scripts, graphs, etc. #### `unlisten_event()` ~~~c void (*unlisten_event)(tm_entity_context_o *ctx, tm_entity_t e, tm_strhash_t event, const tm_entity_event_listener_i *listener); ~~~ Removes a listener registered with `listen_event()`. #### `unlisten_all()` ~~~c void (*unlisten_all)(tm_entity_context_o *ctx, void *instance); ~~~ Removes all listeners using the specified instance. #### `notify_event()` ~~~c void (*notify_event)(tm_entity_context_o *ctx, tm_strhash_t event, tm_entity_t *e, uint32_t entity_stride, void *data, uint32_t data_stride, uint32_t n); ~~~ Triggers the event `event` for the specified list of `n` entities. `e` should point to the first entity. `entity_stride` is the stride in bytes between entities (the entities do not need to be tightly packed, they could be stored as part of the `data`). `data` points to an array of custom data for the events, with `data_stride` being the stride of these events. The data pointer is being passed down to the listener.

#### `set_tag_debug_draw()` ~~~c void (*set_tag_debug_draw)(tm_entity_context_o *ctx, tm_component_type_t component_type, tm_strhash_t tag, bool debug_draw); ~~~ Enable/disable debug drawing for `component_type`, for all entities that have the specified `tag`. If `tag` is 0, debug drawing of the component is enabled for all entities. Note that when disabling debug drawing, only exactly matching entries are disabled. I.e. if you disable `(c, 0)`, any entity/tag pair `(c, tag)` that has been explicitly enabled will still be drawn. #### `set_entity_debug_draw()` ~~~c void (*set_entity_debug_draw)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t component_type, bool debug_draw); ~~~ Enable/disable debug drawing for `component_type`, for the specified entity `e`. #### `get_all_debug_draws()` ~~~c void (*get_all_debug_draws)(tm_entity_context_o *ctx, tm_component_type_t **tag_component_types, tm_strhash_t **tags, tm_component_type_t **entity_component_types, tm_entity_t **entities, struct tm_temp_allocator_i *ta); ~~~ Returns all enabled tag debug draws in the `tag_component_types` and `tags` `carray.inl` arrays, and all enabled entity debug draws in the `entity_component_types` and `entities` `carray.inl` arrays, allocated using the temp allocator. #### `has_tag_debug_draw()` ~~~c bool (*has_tag_debug_draw)(tm_entity_context_o *ctx, tm_component_type_t component_type, tm_strhash_t tag); ~~~ Returns *true* if debug draw is enabled for (`component_type`, `tag`). #### `has_entity_debug_draw()` ~~~c bool (*has_entity_debug_draw)(tm_entity_context_o *ctx, tm_component_type_t component_type, tm_entity_t e); ~~~ Returns *true* if debug draw is enabled for (`component_type`, `e`). #### `clear_debug_draw()` ~~~c void (*clear_debug_draw)(tm_entity_context_o *ctx); ~~~ Clears all debug drawing. #### `debug_draw()` ~~~c void (*debug_draw)(tm_entity_context_o *ctx, struct tm_primitive_drawer_context_t *primitive, const struct tm_camera_t *camera, tm_rect_t viewport); ~~~ Debug draws all entities into the drawing buffers.

#### `propagate_persistence_changes_to_gamestate()` ~~~c void (*propagate_persistence_changes_to_gamestate)(tm_entity_context_o *ctx); ~~~ Propagates changes to all automatically tracked components (i.e., components where `tm_component_persistence_i->manual_tracking` is *false*) into the Gamestate. Note that in order to do this, the function needs to loop over all entities that have these components (a potentially slow operation). #### `propagate_network_replication_changes_to_gamestate()` ~~~c void (*propagate_network_replication_changes_to_gamestate)(tm_entity_context_o *ctx); ~~~ Propagates changes to all structs that needs to be replicated to the gamestate, based on their `watch_timer`. #### `override_component_persistence()` ~~~c void (*override_component_persistence)(tm_entity_context_o *ctx, tm_component_type_t c, tm_component_persistence_i *persistence); ~~~ Override the persistence of the component `c` with `persistence`. This is useful if you want to specify your own persistence for a component for which you cannot edit the original source code. #### `override_component_network_replication()` ~~~c void (*override_component_network_replication)(tm_entity_context_o *ctx, tm_component_type_t c, tm_component_network_replication_i *replication); ~~~ Override the replication of the component `c` with `replication`. This is useful if you want to specify your own replication for a component for which you cannot edit the original source code. #### `set_entity_persistence()` ~~~c void (*set_entity_persistence)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_mask_t *mask, bool persistent); ~~~ Set the entity persistence based on the `persistent` parameter. if `mask` is not NULL only the specified components will be affected. #### `set_entity_replication()` ~~~c void (*set_entity_replication)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_mask_t *mask, bool replicated); ~~~ Set the entity replication based on the `persistent` parameter. if `mask` is not NULL only the specified components will be affected. #### `entity_is_persistent()` ~~~c bool (*entity_is_persistent)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t *component, struct tm_gamestate_object_id_t *o, struct tm_gamestate_struct_id_t *c); ~~~ If `component` is NULL, returns *True* if `e` is persistent, *False* otherwise. Also fills `o` with the entity gamestate id unless `o` is NULL. If `component` is non-zero, returns *True* if the component `c` of `e` is persistent, *False* otherwise. Also fills `c` with the component gamestate id unless `c` is NULL. #### `entity_is_replicated()` ~~~c bool (*entity_is_replicated)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t *component, struct tm_gamestate_object_id_t *o, struct tm_gamestate_struct_id_t *c); ~~~ If `component` is NULL, returns *True* if `e` is replicated, *False* otherwise. Also fills `o` with the entity gamestate id unless `o` is NULL. If `component` is non-zero, returns *True* if the component `c` of `e` is replicated, *False* otherwise. Also fills `c` with the component gamestate id unless `c` is NULL. #### `lookup_entity_from_gamestate_id()` ~~~c tm_entity_t (*lookup_entity_from_gamestate_id)(tm_entity_context_o *ctx, const struct tm_gamestate_object_id_t *id); ~~~ Returns the Entity associated with the specified `id`.
### `tm_entity_api_version`
~~~c #define tm_entity_api_version TM_VERSION(3, 0, 0) ~~~
### `ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG`
~~~c #define ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG TM_STATIC_HASH("entity_gamestate_network_replication", 0xc34de760d3cd3876ULL) ~~~
### `ENTITY_GAMESTATE_PERSISTENCE_CONFIG`
~~~c #define ENTITY_GAMESTATE_PERSISTENCE_CONFIG TM_STATIC_HASH("entity_gamestate_persistence", 0x60e68b48ddbfa1cULL) ~~~
### `union tm_entity_command_entity_handle_t`
~~~c typedef union tm_entity_command_entity_handle_t { struct { uint32_t entity_index; uint32_t asset_index; }; uint64_t u64; } tm_entity_command_entity_handle_t; ~~~ Used to reference newly created entities within a command. Only valid within a command, not shared between commands!
### `struct tm_entity_commands_api`
API for manipulating entity types in a multi-threaded context. Changing an entity's archetype will move it to the new archetype's memory buffer. Since this will shuffle around entities in memory, it's not safe to do when running in a multi-threaded context (such as from an engine or a system). To avoid this you can use the `tm_entity_commands_api` to add such actions to a command queue, that will be executed later at a safe synchronization point. #### `create_entity_from_mask()` ~~~c tm_entity_command_entity_handle_t (*create_entity_from_mask)(tm_entity_commands_o *commands, const tm_component_mask_t *mask); ~~~ As `tm_entity_api->create_entity_from_mask()`, but instead of creating the entity immediately, the command to create the entity is added to `commands`. Returns a handle that represents the entity that will be created when the `commands` are synchronized. This handle can be used to perform additional actions on the entity. #### `batch_create_entity_from_mask()` ~~~c tm_entity_command_entity_handle_t *(*batch_create_entity_from_mask)(struct tm_entity_commands_o *commands, const tm_component_mask_t *mask, uint32_t n, struct tm_temp_allocator_i *ta); ~~~ As `tm_entity_api->batch_create_entity_from_mask()`, but adds the command to `commands`. Returns an array of `tm_entity_command_entity_handle_t` allocated with `ta` that represents the created entities. #### `create_entity_from_asset()` ~~~c tm_entity_command_entity_handle_t (*create_entity_from_asset)(tm_entity_commands_o *commands, tm_tt_id_t asset); ~~~ As `tm_entity_api->create_entity_from_asset()`, but adds the command to `commands` and returns a handle to the entity. #### `batch_create_entity_from_asset()` ~~~c tm_entity_command_entity_handle_t *(*batch_create_entity_from_asset)(tm_entity_commands_o *commands, tm_tt_id_t *asset, uint32_t n, struct tm_temp_allocator_i *ta); ~~~ As `tm_entity_api->batch_create_entity_from_asset()`, but adds the command to `commands` and returns a `carray.inl` of handles to the entities allocated with `ta`. #### `destroy_entity()` ~~~c void (*destroy_entity)(tm_entity_commands_o *commands, tm_entity_t e); ~~~ As `tm_entity_api->destroy_entity()`, but adds the command to `commands`. #### `batch_destroy_entity()` ~~~c void (*batch_destroy_entity)(tm_entity_commands_o *commands, const tm_entity_t *es, uint32_t n); ~~~ As `tm_entity_api->batch_destroy_entity()`, but adds the command to `commands`. #### `clear_world()` ~~~c void (*clear_world)(tm_entity_commands_o *commands); ~~~ As `tm_entity_api->clear_world()`, but adds the command to `commands`. #### `add_component()` ~~~c void *(*add_component)(tm_entity_commands_o *commands, tm_entity_t e, tm_component_type_t component); ~~~ As `tm_entity_api->add_component()`, but adds the command to `commands`. The returned `void *` is a pointer to a zero-initialized temporary memory buffer of the same size as the component data. When the command buffer synchronizes, this data will be copied into the allocated component data for the entity. !!! Note: Note that `add_component()` does not check if the entity already has the component type. If it does, the data written to the temporary buffer returned by `add_component()` will overwrite the existing component data. Important to note is that this function will override any data written to a component on `tm_component_i.add()`. Also note that the entity is not added to the component manager until the command synchronizes. #### `remove_component()` ~~~c void (*remove_component)(tm_entity_commands_o *commands, tm_entity_t e, tm_component_type_t component); ~~~ As `tm_entity_api->remove_component()`, but adds the command to `commands`. #### `add_component_by_handle()` ~~~c void *(*add_component_by_handle)(tm_entity_commands_o *commands, tm_entity_command_entity_handle_t e, tm_component_type_t component); ~~~ As `add_component()`, but uses a handle returned by one of the create functions in this API instead. #### `register_engine()` ~~~c void (*register_engine)(tm_entity_commands_o *commands, const tm_engine_i *engine); ~~~ Registers an engine with the context. #### `remove_engine()` ~~~c void (*remove_engine)(tm_entity_commands_o *commands, tm_strhash_t engine_hash); ~~~ Removes the specified engine from the context. If the engine wasn't registered in the context, this is a NOP, via commands. #### `register_system()` ~~~c void (*register_system)(tm_entity_commands_o *commands, const tm_entity_system_i *system); ~~~ Registers an system with the context. #### `remove_system()` ~~~c void (*remove_system)(tm_entity_commands_o *commands, tm_strhash_t system_hash); ~~~ Removes the specified system from the context. If the system wasn't registered in the context, this is a NOP, via commands.
### `tm_entity_commands_api_version`
~~~c #define tm_entity_commands_api_version TM_VERSION(1, 1, 0) ~~~
### `tm_entity_mask_has_component()`
~~~c static inline bool tm_entity_mask_has_component(const tm_component_mask_t *mask, tm_component_type_t c) { return mask->bits[c.index / 64] & (1ULL << (c.index % 64)); } ~~~
### `tm_entity_mask_add_component()`
~~~c static inline void tm_entity_mask_add_component(tm_component_mask_t *mask, tm_component_type_t c) { mask->bits[c.index / 64] = mask->bits[c.index / 64] | (1ULL << (c.index % 64)); } ~~~
### `tm_entity_mask_remove_component()`
~~~c static inline void tm_entity_mask_remove_component(tm_component_mask_t *mask, tm_component_type_t c) { mask->bits[c.index / 64] = mask->bits[c.index / 64] & ~(1ULL << (c.index % 64)); } ~~~