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

Component configuration
`TM_MAX_COMPONENTS_IN_CONTEXT`
`struct tm_component_mask_t`

`struct tm_component_persistence_i`
`custom_persistent_state`
`size`
`num_members`
`members`
`manual_tracking`
`notify_reload_before_deserialization`
`compute_initial_hash_immediately`
`restore_sort_order`
`user_data`
`serialize()`
`deserialize()`
`compute_hash()`
`compute_asset_hash()`

`tm_component_manager_o`

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

`tm_entity_create_component_i`
`TM_ENTITY_CREATE_COMPONENT_INTERFACE_NAME`

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`
`update()`

`tm_entity_register_engines_i`
`TM_ENTITY_SIMULATION_REGISTER_ENGINES_INTERFACE_NAME`
`TM_ENTITY_EDITOR_REGISTER_ENGINES_INTERFACE_NAME`

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__EDITOR`
`TM_ENTITY_BB__SIMULATING_IN_EDITOR`
`tm_entity_context_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()`
`destroy_context()`
`register_component()`
`num_components()`
`component()`
`register_engine()`
`registered_engines()`
`register_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()`
`destroy_all_entities()`
`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()`
`get_engine()`
`get_system()`

Change propagation
`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()`
`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
`gamestate()`
`override_component_persistence()`
`propagate_changes_to_gamestate()`
`make_entity_persistent()`
`get_entity_gamestate_id()`
`get_component_gamestate_id()`
`lookup_entity_from_gamestate_id()`

`TM_ENTITY_API_NAME`
`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`
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, // The components of the Entity won't be dumped and loaded to and from the Gamestate. TM_ENTITY_PERSISTENCE__NON_PERSISTENT, } tm_entity_persistence; ~~~

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; ~~~
### `struct tm_component_persistence_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: * If `custom_persistent_state` is *false*, the component data blob from the entity context is also used as the serialized data. This works well for simple components. * Otherwise, the `serialize()` and `deserialize()` functions are used to serialize the data into a binary buffer of `size` bytes. If `custom_persistent_state` is *true* and no `serialize()` function is given, the component cannot be serialized, and an error will be thrown. #### `custom_persistent_state` ~~~c bool custom_persistent_state; ~~~ Optional. Controls how the serialization data is generated. If *true*, the `serialize()` and `deserialize()` functions will be used to serialize the data. If *false*, the Entity Context component data blob will also be used as the serialized state. In this case, the `serialize()` and `deserialize()` functions should not be defined and `size` must match the size of the component data. #### `size` ~~~c uint32_t size; ~~~ Optional. Size in bytes of the component's Persistent Gamestate struct. If `custom_persistent_state` is *false*, you can omit this member. The size of the raw component data will be used. If it is *true*, this member specifies the size of the binary data and will be passed as the `buffer_size` argument to the `serialize()` and `deserialize()` functions. #### `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. #### `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_changes_to_gamestate()`. #### `notify_reload_before_deserialization` ~~~c bool notify_reload_before_deserialization; ~~~ Optional. Controls if `asset_reloaded()` should be called before or after the data has been deserialized. If *true*, it will be called before `deserialize()`. If *false*, it will be called after `deserialize()`. #### `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_changes_to_gamestate()` is called. #### `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 `custom_persistent_state` to *false*. 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.
### `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_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, 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, 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, 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, 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, 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. #### `persistence` ~~~c tm_component_persistence_i *persistence; ~~~ Optional. Specifies the persistence settings for the component. If NULL, the component does not support persistence.
### `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_INTERFACE_NAME`
~~~c #define TM_ENTITY_CREATE_COMPONENT_INTERFACE_NAME "tm_entity_create_component_i" ~~~ Interface for creating a component manager (if the component uses one) and registering the component with the entity context.

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); ~~~ 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. #### `update()` ~~~c void (*update)(struct tm_entity_context_o *ctx, tm_entity_system_o *inst); ~~~ Callback function for system update.
### `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_SIMULATION_REGISTER_ENGINES_INTERFACE_NAME` or `TM_ENTITY_EDITOR_REGISTER_ENGINES_INTERFACE_NAME` to run automatically in the "Simulate" or "Preview" tabs.
### `TM_ENTITY_SIMULATION_REGISTER_ENGINES_INTERFACE_NAME`
~~~c #define TM_ENTITY_SIMULATION_REGISTER_ENGINES_INTERFACE_NAME "tm_entity_register_engines_i" ~~~ Used to register a `tm_entity_register_engines_i` that should run in simulation mode with `tm_add_or_remove_implementation()`.
### `TM_ENTITY_EDITOR_REGISTER_ENGINES_INTERFACE_NAME`
~~~c #define TM_ENTITY_EDITOR_REGISTER_ENGINES_INTERFACE_NAME ~~~ Used to register a `tm_entity_register_engines_i` that should run in editor mode with `tm_add_or_remove_implementation()`.

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__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__SIMULATING_IN_EDITOR`
~~~c #define TM_ENTITY_BB__SIMULATING_IN_EDITOR ~~~ Set to non-zero if the simulation is running from within the editor, for example if we are are running a game in the simulation tab. Will be zero when we run a game from the Runner. Note the distinction from `TM_ENTITY_BB__EDITOR`.
### `tm_entity_context_o`
~~~c typedef struct tm_entity_context_o tm_entity_context_o; ~~~ Opaque object representing an entity context.

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_INTERFACE_NAME]] 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_INTERFACE_NAME]] 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. #### `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. #### `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. #### `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. #### `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. #### `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. #### `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); ~~~ #### `destroy_entity()` ~~~c void (*destroy_entity)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Destroys an entity created by create_entity(). #### `batch_destroy_entity()` ~~~c void (*batch_destroy_entity)(tm_entity_context_o *ctx, const tm_entity_t *es, uint32_t n); ~~~ #### `destroy_all_entities()` ~~~c void (*destroy_all_entities)(tm_entity_context_o *ctx); ~~~ #### `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 efficent ways of destroying all data than calling `remove()` on each entity.) #### `get_engine()` ~~~c tm_engine_i *(*get_engine)(tm_entity_context_o *ctx, tm_strhash_t hash); ~~~ Gets the registered engine with the specified `hash`. #### `get_system()` ~~~c tm_entity_system_i *(*get_system)(tm_entity_context_o *ctx, tm_strhash_t hash); ~~~ Gets the registered system with the specified name.

Change propagation

#### `parent()` ~~~c tm_entity_t (*parent)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Returns the parent 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); ~~~ The blackboard is used to hold constant values that can be used by entity engines (without having to be explicitly passed to the instances). A typical use is to pass the delta time. Sets the blackboard item with the specified `id` to `value`. #### `set_blackboard_ptr()` ~~~c void (*set_blackboard_ptr)(tm_entity_context_o *ctx, tm_strhash_t id, void *value); ~~~ #### `has_blackboard()` ~~~c bool (*has_blackboard)(tm_entity_context_o *ctx, tm_strhash_t id); ~~~ Returns true if there is a blackboard item with `id`. #### `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`, or 0 for pointers. #### `get_blackboard_ptr()` ~~~c void *(*get_blackboard_ptr)(tm_entity_context_o *ctx, tm_strhash_t id); ~~~ #### `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. #### `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 find any implmementations of the TM_ENTITY_HOT_RELOAD_* interfaces and run the associated reload callbacks. This makes it possible to update function pointers inside instances of `tm_component_i` and `tm_entity_system_i`.

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

#### `gamestate()` ~~~c struct tm_gamestate_o *(*gamestate)(tm_entity_context_o *ctx); ~~~ Returns the current Gamestate used by 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); ~~~ #### `propagate_changes_to_gamestate()` ~~~c void (*propagate_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). #### `make_entity_persistent()` ~~~c void (*make_entity_persistent)(tm_entity_context_o *ctx, tm_entity_t e); ~~~ Ensures that the Entity `e` is Persistent. #### `get_entity_gamestate_id()` ~~~c bool (*get_entity_gamestate_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_component_gamestate_id()` ~~~c bool (*get_component_gamestate_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_gamestate_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_NAME`
~~~c #define TM_ENTITY_API_NAME "tm_entity_api" ~~~
### `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) ~~~