Flecs: IDs
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
IDs
C API » Core

Functions for working with ecs_id_t. More...

Collaboration diagram for IDs:

## Functions
bool | ecs_id_is_tag (const ecs_world_t *world, ecs_id_t component)
| Return whether a specified component is a tag.
bool | ecs_id_in_use (const ecs_world_t *world, ecs_id_t component)
| Return whether a specified component is in use.
ecs_entity_t | ecs_get_typeid (const ecs_world_t *world, ecs_id_t component)
| Get the type for a component.
bool | ecs_id_match (ecs_id_t component, ecs_id_t pattern)
| Utility to match a component with a pattern.
bool | ecs_id_is_pair (ecs_id_t component)
| Utility to check if a component is a pair.
bool | ecs_id_is_wildcard (ecs_id_t component)
| Utility to check if a component is a wildcard.
bool | ecs_id_is_any (ecs_id_t component)
| Utility to check if a component is an any wildcard.
bool | ecs_id_is_valid (const ecs_world_t *world, ecs_id_t component)
| Utility to check if an ID is valid.
ecs_flags32_t | ecs_id_get_flags (const ecs_world_t *world, ecs_id_t component)
| Get flags associated with an ID.
const char * | ecs_id_flag_str (uint64_t component_flags)
| Convert a component flag to a string.
char * | ecs_id_str (const ecs_world_t *world, ecs_id_t component)
| Convert a component ID to a string.
void | ecs_id_str_buf (const ecs_world_t *world, ecs_id_t component, ecs_strbuf_t *buf)
| Write a component string to a buffer.
ecs_id_t | ecs_id_from_str (const ecs_world_t *world, const char *expr)
| Convert a string to a component.

## Detailed Description

Functions for working with ecs_id_t.

## Function Documentation

## ◆ ecs_get_typeid()

ecs_entity_t ecs_get_typeid | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Get the type for a component.

This operation returns the type for a component ID, if the ID is associated with a type. For a regular component with a non-zero size (an entity with the EcsComponent component), the operation will return the component ID itself.

For an entity that does not have the EcsComponent component, or with an EcsComponent value with size 0, the operation will return 0.

For a pair ID, the operation will return the type associated with the pair, by applying the following queries in order:

- The first pair element is returned if it is a component.
- 0 is returned if the relationship entity has the Tag property.
- The second pair element is returned if it is a component.
- 0 is returned.

Parameters

  world | The world.
  component | The component.

Returns
  The type of the component.

## ◆ ecs_id_flag_str()

const char * ecs_id_flag_str | ( | uint64_t | component_flags | ) |

Convert a component flag to a string.

This operation converts a component flag to a string. Possible outputs are:

- PAIR
- TOGGLE
- AUTO_OVERRIDE

Parameters

  component_flags | The component flag.

Returns
  The ID flag string, or NULL if no valid ID is provided.

## ◆ ecs_id_from_str()

ecs_id_t ecs_id_from_str | ( | const ecs_world_t * | world,
|  | const char * | expr )

Convert a string to a component.

This operation is the reverse of ecs_id_str(). The FLECS_SCRIPT addon is required for this operation to work.

Parameters

  world | The world.
  expr | The string to convert to an ID.

Returns
  The ID, or 0 if the string could not be converted.

## ◆ ecs_id_get_flags()

ecs_flags32_t ecs_id_get_flags | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Get flags associated with an ID.

This operation returns the internal flags (see api_flags.h) that are associated with the provided ID.

Parameters

  world | The world.
  component | The component.

Returns
  The flags associated with the ID, or 0 if the ID is not in use.

## ◆ ecs_id_in_use()

bool ecs_id_in_use | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Return whether a specified component is in use.

This operation returns whether a component is in use in the world. A component is in use if it has been added to one or more tables.

Parameters

  world | The world.
  component | The component.

Returns
  Whether the component is in use.

## ◆ ecs_id_is_any()

bool ecs_id_is_any | ( | ecs_id_t | component | ) |

Utility to check if a component is an any wildcard.

Parameters

  component | The component.

Returns
  True if the component is an any wildcard or a pair containing an any wildcard.

## ◆ ecs_id_is_pair()

bool ecs_id_is_pair | ( | ecs_id_t | component | ) |

Utility to check if a component is a pair.

Parameters

  component | The component.

Returns
  True if the component is a pair.

## ◆ ecs_id_is_tag()

bool ecs_id_is_tag | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Return whether a specified component is a tag.

This operation returns whether the specified component is a tag (a component without data or size).

An ID is a tag when:

- it is an entity without the EcsComponent component
- it has an EcsComponent with size member set to 0
- it is a pair where both elements are a tag
- it is a pair where the first element has the EcsPairIsTag tag

Parameters

  world | The world.
  component | The component.

Returns
  Whether the provided ID is a tag.

## ◆ ecs_id_is_valid()

bool ecs_id_is_valid | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Utility to check if an ID is valid.

A valid ID is an ID that can be added to an entity. Invalid IDs are:

- IDs that contain wildcards
- IDs that contain invalid entities
- IDs that are 0 or contain 0 entities

Note that the same rules apply to removing from an entity, with the exception of wildcards.

Parameters

  world | The world.
  component | The component.

Returns
  True if the ID is valid.

## ◆ ecs_id_is_wildcard()

bool ecs_id_is_wildcard | ( | ecs_id_t | component | ) |

Utility to check if a component is a wildcard.

Parameters

  component | The component.

Returns
  True if the component is a wildcard or a pair containing a wildcard.

## ◆ ecs_id_match()

bool ecs_id_match | ( | ecs_id_t | component,
|  | ecs_id_t | pattern )

Utility to match a component with a pattern.

This operation returns true if the provided pattern matches the provided component. The pattern may contain a wildcard (or wildcards, when a pair).

Parameters

  component | The component.
  pattern | The pattern to compare with.

Returns
  Whether the ID matches the pattern.

## ◆ ecs_id_str()

char * ecs_id_str | ( | const ecs_world_t * | world,
|  | ecs_id_t | component )

Convert a component ID to a string.

This operation converts the provided component ID to a string. It can output strings of the following formats:

- "ComponentName"
- "FLAG|ComponentName"
- "(Relationship, Target)"
- "FLAG|(Relationship, Target)"

The PAIR flag is never added to the string.

Parameters

  world | The world.
  component | The component to convert to a string.

Returns
  The component converted to a string.

## ◆ ecs_id_str_buf()

void ecs_id_str_buf | ( | const ecs_world_t * | world,
|  | ecs_id_t | component,
|  | ecs_strbuf_t * | buf )

Write a component string to a buffer.

Same as ecs_id_str(), but writes the result to ecs_strbuf_t.

Parameters

  world | The world.
  component | The component to convert to a string.
  buf | The buffer to write to.