Entity Information.

Get information from entity. More...

Collaboration diagram for Entity Information.:

Classes
struct	ecs_flatten_desc_t

Typedefs
typedef struct ecs_flatten_desc_t	ecs_flatten_desc_t

Functions
const ecs_type_t *	ecs_get_type (const ecs_world_t *world, ecs_entity_t entity)
	Get the type of an entity.
ecs_table_t *	ecs_get_table (const ecs_world_t *world, ecs_entity_t entity)
	Get the table of an entity.
char *	ecs_type_str (const ecs_world_t *world, const ecs_type_t *type)
	Convert type to string.
char *	ecs_table_str (const ecs_world_t *world, const ecs_table_t *table)
	Convert table to string.
char *	ecs_entity_str (const ecs_world_t *world, ecs_entity_t entity)
	Convert entity to string.
bool	ecs_has_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
	Test if an entity has an id.
bool	ecs_owns_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
	Test if an entity owns an id.
ecs_entity_t	ecs_get_target (const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel, int32_t index)
	Get the target of a relationship.
ecs_entity_t	ecs_get_parent (const ecs_world_t *world, ecs_entity_t entity)
	Get parent (target of ChildOf relationship) for entity.
ecs_entity_t	ecs_get_target_for_id (const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel, ecs_id_t id)
	Get the target of a relationship for a given id.
int32_t	ecs_get_depth (const ecs_world_t *world, ecs_entity_t entity, ecs_entity_t rel)
	Return depth for entity in tree for the specified relationship.
void	ecs_flatten (ecs_world_t *world, ecs_id_t pair, const ecs_flatten_desc_t *desc)
	Recursively flatten relationship for target entity (experimental).
int32_t	ecs_count_id (const ecs_world_t *world, ecs_id_t entity)
	Count entities that have the specified id.

Detailed Description

Get information from entity.

Function Documentation

ecs_count_id()

int32_t ecs_count_id	(	const ecs_world_t *	world,
		ecs_id_t	entity )

Count entities that have the specified id.

Returns the number of entities that have the specified id.

Parameters

world	The world.
entity	The id to search for.

Returns

The number of entities that have the id.

ecs_entity_str()

char * ecs_entity_str	(	const ecs_world_t *	world,
		ecs_entity_t	entity )

Convert entity to string.

Same as combining:

• ecs_get_fullpath(world, entity)
• ecs_type_str(world, ecs_get_type(world, entity))

The result of this operation must be freed with ecs_os_free().

Parameters

world	The world.
entity	The entity.

Returns

The entity path with stringified type.

ecs_flatten()

void ecs_flatten	(	ecs_world_t *	world,
		ecs_id_t	pair,
		const ecs_flatten_desc_t *	desc )

Recursively flatten relationship for target entity (experimental).

This operation combines entities in the subtree of the specified pair from different parents in the same table. This can reduce memory fragmentation and reduces the number of tables in the storage, which improves RAM utilization and various other operations, such as entity cleanup.

The lifecycle of entities in a fixed subtree are bound to the specified parent. Entities in a fixed subtree cannot be deleted individually. Entities can also not change the target of the fixed relationship, which includes removing the relationship.

Entities in a fixed subtree are still fragmented on subtree depth. This ensures that entities can still be iterated in breadth-first order with the cascade query modifier.

The current implementation is limited to exclusive acyclic relationships, and does not allow for adding/removing to entities in flattened tables. An entity may only be flattened for a single relationship. Future iterations of the feature may remove these limitations.

Parameters

world	The world.
pair	The relationship pair from which to start flattening.
desc	Options for flattening the tree.

ecs_get_depth()

int32_t ecs_get_depth	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_entity_t	rel )

Return depth for entity in tree for the specified relationship.

Depth is determined by counting the number of targets encountered while traversing up the relationship tree for rel. Only acyclic relationships are supported.

Parameters

world	The world.
entity	The entity.
rel	The relationship.

Returns

The depth of the entity in the tree.

ecs_get_parent()

ecs_entity_t ecs_get_parent	(	const ecs_world_t *	world,
		ecs_entity_t	entity )

Get parent (target of ChildOf relationship) for entity.

This operation is the same as calling:

ecs_get_target(world, entity, EcsChildOf, 0);

Parameters

world	The world.
entity	The entity.

Returns

The parent of the entity, 0 if the entity has no parent.

ecs_get_table()

ecs_table_t * ecs_get_table	(	const ecs_world_t *	world,
		ecs_entity_t	entity )

Get the table of an entity.

Parameters

world	The world.
entity	The entity.

Returns

The table of the entity, NULL if the entity has no components/tags.

ecs_get_target()

ecs_entity_t ecs_get_target	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_entity_t	rel,
		int32_t	index )

Get the target of a relationship.

This will return a target (second element of a pair) of the entity for the specified relationship. The index allows for iterating through the targets, if a single entity has multiple targets for the same relationship.

If the index is larger than the total number of instances the entity has for the relationship, the operation will return 0.

Parameters

world	The world.
entity	The entity.
rel	The relationship between the entity and the target.
index	The index of the relationship instance.

Returns

The target for the relationship at the specified index.

ecs_get_target_for_id()

ecs_entity_t ecs_get_target_for_id	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_entity_t	rel,
		ecs_id_t	id )

Get the target of a relationship for a given id.

This operation returns the first entity that has the provided id by following the specified relationship. If the entity itself has the id then entity will be returned. If the id cannot be found on the entity or by following the relationship, the operation will return 0.

This operation can be used to lookup, for example, which prefab is providing a component by specifying the IsA relationship:

// Is Position provided by the entity or one of its base entities?
ecs_get_target_for_id(world, entity, EcsIsA, ecs_id(Position))

Parameters

world	The world.
entity	The entity.
rel	The relationship to follow.
id	The id to lookup.

Returns

The entity for which the target has been found.

ecs_get_type()

const ecs_type_t * ecs_get_type	(	const ecs_world_t *	world,
		ecs_entity_t	entity )

Get the type of an entity.

Parameters

world	The world.
entity	The entity.

Returns

The type of the entity, NULL if the entity has no components.

ecs_has_id()

bool ecs_has_id	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_id_t	id )

Test if an entity has an id.

This operation returns true if the entity has or inherits the specified id.

Parameters

world	The world.
entity	The entity.
id	The id to test for.

Returns

True if the entity has the id, false if not.

ecs_owns_id()

bool ecs_owns_id	(	const ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_id_t	id )

Test if an entity owns an id.

This operation returns true if the entity has the specified id. The operation behaves the same as ecs_has_id(), except that it will return false for components that are inherited through an IsA relationship.

Parameters

world	The world.
entity	The entity.
id	The id to test for.

Returns

True if the entity has the id, false if not.

ecs_table_str()

char * ecs_table_str	(	const ecs_world_t *	world,
		const ecs_table_t *	table )

Convert table to string.

Same as ecs_type_str(world, ecs_table_get_type(table)). The result of this operation must be freed with ecs_os_free().

Parameters

world	The world.
table	The table.

Returns

The stringified table type.

ecs_type_str()

char * ecs_type_str	(	const ecs_world_t *	world,
		const ecs_type_t *	type )

Convert type to string.

The result of this operation must be freed with ecs_os_free().

Parameters

world	The world.
type	The type.

Returns

The stringified type.