Functions for testing and modifying entity liveliness. More...

Functions
bool	ecs_is_valid (const ecs_world_t *world, ecs_entity_t e)
	Test whether an entity is valid. More...

bool	ecs_is_alive (const ecs_world_t *world, ecs_entity_t e)
	Test whether an entity is alive. More...

ecs_id_t	ecs_strip_generation (ecs_entity_t e)
	Remove generation from entity id. More...

void	ecs_set_entity_generation (ecs_world_t *world, ecs_entity_t entity)
	Override the generation of an entity. More...

ecs_entity_t	ecs_get_alive (const ecs_world_t *world, ecs_entity_t e)
	Get alive identifier. More...

void	ecs_ensure (ecs_world_t *world, ecs_entity_t entity)
	Ensure id is alive. More...

void	ecs_ensure_id (ecs_world_t *world, ecs_id_t id)
	Same as ecs_ensure, but for (component) ids. More...

bool	ecs_exists (const ecs_world_t *world, ecs_entity_t entity)
	Test whether an entity exists. More...

Detailed Description

Functions for testing and modifying entity liveliness.

Function Documentation

◆ ecs_ensure()

void ecs_ensure	(	ecs_world_t *	world,
		ecs_entity_t	entity
	)

Ensure id is alive.

This operation ensures that the provided id is alive. This is useful in scenarios where an application has an existing id that has not been created with ecs_new (such as a global constant or an id from a remote application).

When this operation is successful it guarantees that the provided id exists, is valid and is alive.

Before this operation the id must either not be alive or have a generation that is equal to the passed in entity.

If the provided id has a non-zero generation count and the id does not exist in the world, the id will be created with the specified generation.

If the provided id is alive and has a generation count that does not match the provided id, the operation will fail.

Parameters

world	The world.
entity	The entity id to make alive.

◆ ecs_ensure_id()

void ecs_ensure_id	(	ecs_world_t *	world,
		ecs_id_t	id
	)

Same as ecs_ensure, but for (component) ids.

An id can be an entity or pair, and can contain id flags. This operation ensures that the entity (or entities, for a pair) are alive.

When this operation is successful it guarantees that the provided id can be used in operations that accept an id.

Since entities in a pair do not encode their generation ids, this operation will not fail when an entity with non-zero generation count already exists in the world.

This is different from ecs_ensure, which will fail if attempted with an id that has generation 0 and an entity with a non-zero generation is currently alive.

Parameters

world	The world.
id	The id to make alive.

◆ ecs_exists()

bool ecs_exists	(	const ecs_world_t *	world,
		ecs_entity_t	entity
	)

Test whether an entity exists.

Similar as ecs_is_alive, but ignores entity generation count.

Parameters

world	The world.
entity	The entity.

Returns: True if the entity exists, false if the entity does not exist.

◆ ecs_get_alive()

ecs_entity_t ecs_get_alive	(	const ecs_world_t *	world,
		ecs_entity_t	e
	)

Get alive identifier.

In some cases an application may need to work with identifiers from which the generation has been stripped. A typical scenario in which this happens is when iterating relationships in an entity type.

For example, when obtaining the parent id from a ChildOf relationship, the parent (second element of the pair) will have been stored in a 32 bit value, which cannot store the entity generation. This function can retrieve the identifier with the current generation for that id.

If the provided identifier is not alive, the function will return 0.

Parameters

world	The world.
e	The for which to obtain the current alive entity id.

Returns: The alive entity id if there is one, or 0 if the id is not alive.

◆ ecs_is_alive()

bool ecs_is_alive	(	const ecs_world_t *	world,
		ecs_entity_t	e
	)

Test whether an entity is alive.

An entity is alive when it has been returned by ecs_new (or similar) or if it is not empty (componentts have been explicitly added to the id).

Parameters

world	The world.
e	The entity.

Returns: True if the entity is alive, false if the entity is not alive.

◆ ecs_is_valid()

bool ecs_is_valid	(	const ecs_world_t *	world,
		ecs_entity_t	e
	)

Test whether an entity is valid.

Entities that are valid can be used with API functions.

An entity is valid if it is not 0 and if it is alive. If the provided id is a pair, the contents of the pair will be checked for validity.

is_valid will return true for ids that don't exist (alive or not alive). This allows for using ids that have never been created by ecs_new or similar. In this the function differs from ecs_is_alive, which will return false for entities that do not yet exist.

The operation will return false for an id that exists and is not alive, as using this id with an API operation would cause it to assert.

Parameters

world	The world.
e	The entity.

Returns: True if the entity is valid, false if the entity is not valid.

◆ ecs_set_entity_generation()

void ecs_set_entity_generation	(	ecs_world_t *	world,
		ecs_entity_t	entity
	)

Override the generation of an entity.

The generation count of an entity is increased each time an entity is deleted and is used to test whether an entity id is alive.

This operation overrides the current generation of an entity with the specified generation, which can be useful if an entity is externally managed, like for external pools, savefiles or netcode.

Parameters

world	The world.
entity	Entity for which to set the generation with the new generation.

◆ ecs_strip_generation()

ecs_id_t ecs_strip_generation ( ecs_entity_t e )

Remove generation from entity id.

Parameters

e	The entity id.

Returns: The entity id without the generation count.