# 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`
`enum TM_TT_PROP__ENTITY_SORT_VALUE`
`TM_TT_TYPE__ENTITY`
`enum TM_TT_PROP__ENTITY`
`enum tm_entity_persistence`

Opaque types
`tm_entity_context_o`
`tm_entity_commands_o`

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_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`

`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__CAMERA`
`TM_ENTITY_BB__DISABLED_INPUT`
`TM_ENTITY_BB__EDITOR`
`TM_ENTITY_BB__ASSET_ROOT`
`tm_entity_context_o`
`tm_entity_commands_o`

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`

Creating and setting up the context
`create_truth_types()`
`create_context()`
`create_components()`
`destroy_context()`
`register_component()`
`disable_component()`
`num_components()`
`component()`
`register_engine()`
`remove_engine()`
`registered_engines()`
`register_system()`
`remove_system()`
`registered_systems()`
`create_child_allocator()`
`destroy_child_allocator()`
`the_truth()`

Creating and destroying entities
`create_entity()`
`batch_create_entity()`
`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()`
`queue_destroy_entities()`
`is_alive()`

Finding entities
`num_entities()`
`entities_matching()`
`entities_matching_with_forbidden()`
`flatten_set()`

Accessing components
`lookup_component_type()`
`component_manager()`
`component_manager_by_hash()`
`create_component_mask()`
`component_mask()`
`add_component()`
`get_component()`
`get_component_by_hash()`
`remove_component()`
`call_remove_on_all_entities()`

Change propagation
`asset_parent()`
`children()`
`asset()`
`find_entity_from_asset()`
`resolve_asset_reference()`
`resolve_path()`
`propagate_asset_changes()`
`propagate_listen_to()`

Update
`set_blackboard_double()`
`set_blackboard_ptr()`
`has_blackboard()`
`get_blackboard_double()`
`get_blackboard_ptr()`
`run_engine()`
`run_engine_with_commands()`
`update()`

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

Hot reload
`hot_reload()`

Debug drawing
`set_debug_draw()`
`get_all_debug_draws()`
`has_debug_draw()`
`clear_debug_draw()`
`debug_draw()`
`gamestate()`
`override_component_persistence()`
`override_component_network_replication()`
`propagate_persistence_changes_to_gamestate()`
`propagate_network_replication_changes_to_gamestate()`
`ensure_entity_is_persistent()`
`ensure_entity_is_replicated()`
`get_entity_persistent_id()`
`get_entity_network_id()`
`get_component_persistent_id()`
`get_component_network_id()`
`lookup_entity_from_gamestate_id()`

`tm_entity_api_version`
`ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG`
`struct 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()`

`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" #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" #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__PERSISTENCE, // uint32_t [[enum tm_entity_persistence]] }; ~~~
### `enum tm_entity_persistence`
TODO(Leonardo): We could easily have two separated concept to express the concept of `persistence` and `network_replication`. There's no reason other than avoid cluttering the Entity Tree as to why a `network_replicated` entity should also be persistent. Specifies the how an entity is persisted to the Gamestate. ~~~c typedef enum tm_entity_persistence { // Specifies that persistence settings are inherited from the entity's parent or from the root // entity of the world for entity's that do not have a parent. // // This is the default option. TM_ENTITY_PERSISTENCE__INHERIT, // All the components of the Entity that have a [[tm_component_persistence_i]] attached to them // will be dumped and loaded back from the Gamestate. TM_ENTITY_PERSISTENCE__PERSISTENT, // Same as TM_ENTITY_PERSISTENCE_PERSISTENT. // In addition, All the components of the Entity that have a [[tm_component_network_replication_i]] attached to them // will be replicated. TM_ENTITY_PERSISTENCE__PERSISTENT_REPLICATED, // The components of the Entity won't be dumped and loaded to and from the Gamestate. TM_ENTITY_PERSISTENCE__NON_PERSISTENT, } tm_entity_persistence; ~~~

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.

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_hash_immediately` ~~~c bool compute_initial_hash_immediately; ~~~ Optional. Determines if the hash of the component can be computed lazily. 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, 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 `get_component()`. That could let us do more efficient batch processing. #### `deserialize()` ~~~c void (*deserialize)(struct tm_entity_context_o *ctx, 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; ~~~ #### `shared_members` ~~~c struct tm_gamestate_member_t *shared_members; ~~~
### `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. If this is not specified, a single opaque field that represents the entire binary struct 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. If this is not specified, a single opaque field that represents the entire binary struct will be used.
### `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 won't ever be checked. double watch_timer; 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 won't ever be checked. #### `num_members` ~~~c uint32_t num_members; ~~~ #### `members` ~~~c struct tm_gamestate_member_t *members; ~~~ #### `member_replication` ~~~c tm_member_network_replication_t *member_replication; ~~~
### `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); ~~~ Optional callback when the component is added to an entity. #### `remove()` ~~~c void (*remove)(tm_component_manager_o *manager, struct tm_entity_commands_o *commands, tm_entity_t e, void *data); ~~~ Optional callback when the component is removed from an entity. #### `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_buffer_t *pbuf, struct tm_primitive_drawer_buffer_t *vbuf, struct tm_allocator_i *allocator, 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; ~~~ #### `persistence` ~~~c tm_component_persistence_i *persistence; ~~~ Optional. Specifies the persistence settings for the component. If NULL, the component does not support persistence. #### `network_replication` ~~~c tm_component_network_replication_i *network_replication; ~~~
### `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 ~~~ Current version of `tm_entity_create_component_i`.

Engines and systems

### `TM_MAX_COMPONENTS_FOR_ENGINE`
~~~c #define TM_MAX_COMPONENTS_FOR_ENGINE 16 ~~~ 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 ~~~ 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 ~~~ Phase for physics jobs.
### `TM_PHASE__GRAPH`
~~~c #define TM_PHASE__GRAPH ~~~ Phase for the visual scripting graph update.
### `TM_PHASE__CAMERA`
~~~c #define TM_PHASE__CAMERA ~~~ Phase for camera jobs.
### `TM_PHASE__RENDER`
~~~c #define TM_PHASE__RENDER ~~~ 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 `get_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_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 ~~~

Blackboard

### `TM_ENTITY_BB__SIMULATION_SPEED`
~~~c #define TM_ENTITY_BB__SIMULATION_SPEED ~~~ 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 ~~~ Blackboard item representing the simulation delta time of the current frame.
### `TM_ENTITY_BB__TIME`
~~~c #define TM_ENTITY_BB__TIME ~~~ Blackboard item representing the total elapsed time in the simulation.
### `TM_ENTITY_BB__WALL_DELTA_TIME`
~~~c #define TM_ENTITY_BB__WALL_DELTA_TIME ~~~ 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 ~~~ Blackboard item representing the total elapsed wall time in the simulation.
### `TM_ENTITY_BB__UI`
~~~c #define TM_ENTITY_BB__UI #define TM_ENTITY_BB__UI_STYLE #define TM_ENTITY_BB__UI_RECT #define TM_ENTITY_BB__UI_VIEWPORT_RECT #define TM_ENTITY_BB__WINDOW ~~~ 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__CAMERA`
~~~c #define TM_ENTITY_BB__CAMERA #define TM_ENTITY_BB__CAMERA_TRANSFORM ~~~ Blackboard items for the current camera.
### `TM_ENTITY_BB__DISABLED_INPUT`
~~~c #define TM_ENTITY_BB__DISABLED_INPUT ~~~
### `TM_ENTITY_BB__EDITOR`
~~~c #define TM_ENTITY_BB__EDITOR ~~~ 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 ~~~ Blackboard item for accessing the asset root.
### `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 an entity commands.

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...

Creating and setting up the context

#### `create_truth_types()` ~~~c void (*create_truth_types)(struct tm_the_truth_o *tt); ~~~ Creates The Truth types used by the entity system #### `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); ~~~ Creates a new simulation context where entities live. #### `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()` in between the call to `create_context()` and `create_components()` #### `destroy_context()` ~~~c void (*destroy_context)(tm_entity_context_o *ctx); ~~~ Destroys a simulation context created by `create_context()`. #### `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); ~~~ Disable the specified component. Note that for this call to have effect the context creation process has to follow these steps: -Create the entity context specifying `TM_ENTITY_CREATE_COMPONENTS_NONE` -Disable all the components that have to be disabled by calling `disable_component()` -finish component creation by calling `create_components()` #### `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. #### `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 current frame. #### `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. #### `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 current frame. #### `registered_systems()` ~~~c tm_entity_system_i *(*registered_systems)(tm_entity_context_o *ctx, uint32_t *count); ~~~ Returns all registered systems. #### `create_child_allocator()` ~~~c void (*create_child_allocator)(tm_entity_context_o *ctx, const char *name, struct tm_allocator_i *a); ~~~ Creates/destroys a child allocator to 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); ~~~ #### `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.

Creating and destroying entities

#### `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); ~~~ !!! 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->batch_create_entity_from_mask()`. #### `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); ~~~ !!! 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->batch_create_entity_from_asset()`. #### `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); ~~~ !!! 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()`. #### `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()`. #### `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. #### `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.

Finding entities

#### `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, 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.) The set is allocated using the temp allocator. #### `entities_matching_with_forbidden()` ~~~c tm_entity_set_t *(*entities_matching_with_forbidden)(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, 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`.

Accessing components

#### `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. #### `get_component()` ~~~c void *(*get_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. #### `get_component_by_hash()` ~~~c void *(*get_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. #### `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. #### `call_remove_on_all_entities()` ~~~c void (*call_remove_on_all_entities)(tm_entity_context_o *ctx, tm_component_type_t component); ~~~ Calls the `tm_component_i->remove()` callback on all entities that have the specified component. This can be useful to implement `tm_component_i->destroy()`, since `destroy()` doesn't automatically call `remove()`. (Because sometimes there are more efficient ways of destroying all data than calling `remove()` on each entity.)

Change propagation

#### `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. #### `children()` ~~~c tm_entity_t *(*children)(tm_entity_context_o *ctx, tm_entity_t e, struct tm_temp_allocator_i *ta); ~~~ Returns the children of the entity `e`. The children are returned as a `carray`, allocated by the temp allocator `ta`. Note: This is a wrapper around `tm_owner_component_api->children()`. The children of an entity are tracked by the (hidden) owner component. #### `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_entity_from_asset()` ~~~c tm_entity_t (*find_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. #### `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_path()` ~~~c tm_entity_t (*resolve_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. #### `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).

Update

#### `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. #### `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. #### `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)

Notifications

#### `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.

Hot reload

#### `hot_reload()` ~~~c void (*hot_reload)(void); ~~~ Should be called whenever a hot reload has occurred. Will re-register all engines and go over all systems and run their `hot_reload` function, if it exists.

Debug drawing

#### `set_debug_draw()` ~~~c void (*set_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. #### `get_all_debug_draws()` ~~~c void (*get_all_debug_draws)(tm_entity_context_o *ctx, tm_component_type_t **component_types, tm_strhash_t **tags, struct tm_temp_allocator_i *ta); ~~~ Returns all enabled debug draws in the `component_types` and `tags` `carray.inl` arrays, allocated using the temp allocator. #### `has_debug_draw()` ~~~c bool (*has_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`). #### `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_buffer_t *pbuf, struct tm_primitive_drawer_buffer_t *vbuf, struct tm_allocator_i *allocator, const struct tm_camera_t *camera, tm_rect_t viewport); ~~~ Debug draws all entities into the drawing buffers. #### `gamestate()` ~~~c struct tm_gamestate_o *(*gamestate)(tm_entity_context_o *ctx); ~~~ Gamestate Returns the Gamestate currently binded to the entity context. #### `override_component_persistence()` ~~~c void (*override_component_persistence)(tm_entity_context_o *ctx, tm_component_type_t c, tm_component_persistence_i *persistence); ~~~ #### `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); ~~~ #### `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); ~~~ #### `ensure_entity_is_persistent()` ~~~c void (*ensure_entity_is_persistent)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Ensures that the Entity `e` is Persistent. #### `ensure_entity_is_replicated()` ~~~c void (*ensure_entity_is_replicated)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Ensures that the Entity `e` is Replicated across the network. #### `get_entity_persistent_id()` ~~~c bool (*get_entity_persistent_id)(tm_entity_context_o *ctx, tm_entity_t e, struct tm_gamestate_object_id_t *output); ~~~ If the Entity `e` is Persistent, fills `output` with its persistent id and returns *true*. Otherwise, returns *false*. #### `get_entity_network_id()` ~~~c bool (*get_entity_network_id)(tm_entity_context_o *ctx, tm_entity_t e, struct tm_gamestate_object_id_t *output); ~~~ If the Entity `e` should be replicated across the network, fills `output` with its persistent id and returns *true*. Otherwise, returns *false*. #### `get_component_persistent_id()` ~~~c bool (*get_component_persistent_id)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t c, struct tm_gamestate_struct_id_t *output); ~~~ As `get_entity_persistent_id()` but returns the Gamestate id of a specific component in the entity. #### `get_component_network_id()` ~~~c bool (*get_component_network_id)(tm_entity_context_o *ctx, tm_entity_t e, tm_component_type_t c, struct tm_gamestate_struct_id_t *output); ~~~ As `get_entity_network_id()` but returns the Gamestate id of a specific component in the entity. #### `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 ~~~
### `ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG`
~~~c #define ENTITY_GAMESTATE_NETWORK_REPLICATION_CONFIG #define ENTITY_GAMESTATE_PERSISTENCE_CONFIG ~~~
### `struct 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 /* carray */ 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 /* carray */ 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.
### `tm_entity_commands_api_version`
~~~c #define tm_entity_commands_api_version ~~~
### `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) ~~~
### `tm_entity_mask_add_component()`
~~~c static inline void tm_entity_mask_add_component(tm_component_mask_t *mask, tm_component_type_t c) ~~~
### `tm_entity_mask_remove_component()`
~~~c static inline void tm_entity_mask_remove_component(tm_component_mask_t *mask, tm_component_type_t c) ~~~