Flecs: Entity Liveliness
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Entity Liveliness
C API » Core » Entities

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

Collaboration diagram for Entity Liveliness:

## Functions
bool | ecs_is_valid (const ecs_world_t *world, ecs_entity_t e)
| Test whether an entity is valid.
bool | ecs_is_alive (const ecs_world_t *world, ecs_entity_t e)
| Test whether an entity is alive.
ecs_id_t | ecs_strip_generation (ecs_entity_t e)
| Remove the generation from an entity ID.
ecs_entity_t | ecs_get_alive (const ecs_world_t *world, ecs_entity_t e)
| Get an alive identifier.
void | ecs_make_alive (ecs_world_t *world, ecs_entity_t entity)
| Ensure an ID is alive.
void | ecs_make_alive_id (ecs_world_t *world, ecs_id_t component)
| Same as ecs_make_alive(), but for components.
bool | ecs_exists (const ecs_world_t *world, ecs_entity_t entity)
| Test whether an entity exists.
void | ecs_set_version (ecs_world_t *world, ecs_entity_t entity)
| Override the generation of an entity.
uint32_t | ecs_get_version (ecs_entity_t entity)
| Get the generation of an entity.

## Detailed Description

Functions for testing and modifying entity liveliness.

## Function Documentation

## ◆ ecs_exists()

bool ecs_exists | ( | const ecs_world_t * | world,
|  | ecs_entity_t | entity )

Test whether an entity exists.

Similar to ecs_is_alive(), but ignores the 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 an 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 entity 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_get_version()

uint32_t ecs_get_version | ( | ecs_entity_t | entity | ) |

Get the generation of an entity.

Parameters

  entity | The entity for which to get the generation.

Returns
  The generation of the entity.

## ◆ ecs_is_alive()

bool ecs_is_alive | ( | const ecs_world_t * | world,
|  | ecs_entity_t | e )

Test whether an entity is alive.

Entities are alive after they are created, and become not alive when they are deleted. Operations that return alive IDs are (amongst others) ecs_new(), ecs_new_low_id() and ecs_entity_init(). IDs can be made alive with the ecs_make_alive() function.

After an ID is deleted it can be recycled. Recycled IDs are different from the original ID in that they have a different generation count. This makes it possible for the API to distinguish between the two. An example:

ecs_entity_t e1 = ecs_new(world);
ecs_is_alive(world, e1); // true
ecs_delete(world, e1);
ecs_is_alive(world, e1); // false
ecs_entity_t e2 = ecs_new(world); // recycles e1
ecs_is_alive(world, e2); // true
ecs_is_alive(world, e1); // false
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:385
ecs_new
ecs_entity_t ecs_new(ecs_world_t *world)
Create new entity ID.
ecs_delete
void ecs_delete(ecs_world_t *world, ecs_entity_t entity)
Delete an entity.
ecs_is_alive
bool ecs_is_alive(const ecs_world_t *world, ecs_entity_t e)
Test whether an entity is alive.

Unlike ecs_is_valid(), this operation will panic if the passed-in entity ID is 0 or has an invalid bit pattern.

Parameters

  world | The world.
  e | The entity.

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

See also
  ecs_is_valid()

## ◆ ecs_is_valid()

bool ecs_is_valid | ( | const ecs_world_t * | world,
|  | ecs_entity_t | e )

Test whether an entity is valid.

This operation tests whether the entity ID:

- is not 0
- has a valid bit pattern
- is alive (see ecs_is_alive())

If this operation returns true, it is safe to use the entity with other operations.

This operation should only be used if an application cannot be sure that an entity is initialized with a valid value. In all other cases where an entity was initialized with a valid value, but the application wants to check if the entity is (still) alive, use ecs_is_alive().

Parameters

  world | The world.
  e | The entity.

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

See also
  ecs_is_alive()

## ◆ ecs_make_alive()

void ecs_make_alive | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity )

Ensure an 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_w() (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.

See also
  ecs_make_alive_id()

## ◆ ecs_make_alive_id()

void ecs_make_alive_id | ( | ecs_world_t * | world,
|  | ecs_id_t | component )

Same as ecs_make_alive(), but for components.

An ID can be an entity or a 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_make_alive(), 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.
  component | The component to make alive.

## ◆ ecs_set_version()

void ecs_set_version | ( | 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.

This operation is similar to ecs_make_alive(), except that it will also override the generation of an alive entity.

Parameters

  world | The world.
  entity | The entity for which to set the generation.

## ◆ ecs_strip_generation()

ecs_id_t ecs_strip_generation | ( | ecs_entity_t | e | ) |

Remove the generation from an entity ID.

Parameters

  e | The entity ID.

Returns
  The entity ID without the generation count.