Flecs: Entity Names
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 Names
C API » Core » Entities

Functions for working with entity names and paths. More...

Collaboration diagram for Entity Names:

## Functions
const char * | ecs_get_name (const ecs_world_t *world, ecs_entity_t entity)
| Get the name of an entity.
const char * | ecs_get_symbol (const ecs_world_t *world, ecs_entity_t entity)
| Get the symbol of an entity.
ecs_entity_t | ecs_set_name (ecs_world_t *world, ecs_entity_t entity, const char *name)
| Set the name of an entity.
ecs_entity_t | ecs_set_symbol (ecs_world_t *world, ecs_entity_t entity, const char *symbol)
| Set the symbol of an entity.
void | ecs_set_alias (ecs_world_t *world, ecs_entity_t entity, const char *alias)
| Set alias for entity.
ecs_entity_t | ecs_lookup (const ecs_world_t *world, const char *path)
| Lookup an entity by it's path.
ecs_entity_t | ecs_lookup_child (const ecs_world_t *world, ecs_entity_t parent, const char *name)
| Lookup a child entity by name.
ecs_entity_t | ecs_lookup_path_w_sep (const ecs_world_t *world, ecs_entity_t parent, const char *path, const char *sep, const char *prefix, bool recursive)
| Lookup an entity from a path.
ecs_entity_t | ecs_lookup_symbol (const ecs_world_t *world, const char *symbol, bool lookup_as_path, bool recursive)
| Lookup an entity by its symbol name.
char * | ecs_get_path_w_sep (const ecs_world_t *world, ecs_entity_t parent, ecs_entity_t child, const char *sep, const char *prefix)
| Get a path identifier for an entity.
void | ecs_get_path_w_sep_buf (const ecs_world_t *world, ecs_entity_t parent, ecs_entity_t child, const char *sep, const char *prefix, ecs_strbuf_t *buf, bool escape)
| Write path identifier to buffer.
ecs_entity_t | ecs_new_from_path_w_sep (ecs_world_t *world, ecs_entity_t parent, const char *path, const char *sep, const char *prefix)
| Find or create entity from path.
ecs_entity_t | ecs_add_path_w_sep (ecs_world_t *world, ecs_entity_t entity, ecs_entity_t parent, const char *path, const char *sep, const char *prefix)
| Add specified path to entity.
ecs_entity_t | ecs_set_scope (ecs_world_t *world, ecs_entity_t scope)
| Set the current scope.
ecs_entity_t | ecs_get_scope (const ecs_world_t *world)
| Get the current scope.
const char * | ecs_set_name_prefix (ecs_world_t *world, const char *prefix)
| Set a name prefix for newly created entities.
ecs_entity_t * | ecs_set_lookup_path (ecs_world_t *world, const ecs_entity_t *lookup_path)
| Set search path for lookup operations.
ecs_entity_t * | ecs_get_lookup_path (const ecs_world_t *world)
| Get current lookup path.

## Detailed Description

Functions for working with entity names and paths.

## Function Documentation

## ◆ ecs_add_path_w_sep()

ecs_entity_t ecs_add_path_w_sep | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_entity_t | parent,
|  | const char * | path,
|  | const char * | sep,
|  | const char * | prefix )

Add specified path to entity.

This operation is similar to ecs_new_from_path(), but will instead add the path to an existing entity.

If an entity already exists for the path, it will be returned instead.

Parameters

  world | The world.
  entity | The entity to which to add the path.
  parent | The entity relative to which the entity should be created.
  path | The path to create the entity for.
  sep | The separator used in the path.
  prefix | The prefix used in the path.

Returns
  The entity.

## ◆ ecs_get_lookup_path()

ecs_entity_t * ecs_get_lookup_path | ( | const ecs_world_t * | world | ) |

Get current lookup path.

Returns value set by ecs_set_lookup_path().

Parameters

  world | The world.

Returns
  The current lookup path.

## ◆ ecs_get_name()

const char * ecs_get_name | ( | const ecs_world_t * | world,
|  | ecs_entity_t | entity )

Get the name of an entity.

This will return the name stored in (EcsIdentifier, EcsName).

Parameters

  world | The world.
  entity | The entity.

Returns
  The type of the entity, NULL if the entity has no name.

See also
  ecs_set_name()

## ◆ ecs_get_path_w_sep()

char * ecs_get_path_w_sep | ( | const ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | ecs_entity_t | child,
|  | const char * | sep,
|  | const char * | prefix )

Get a path identifier for an entity.

This operation creates a path that contains the names of the entities from the specified parent to the provided entity, separated by the provided separator. If no parent is provided the path will be relative to the root. If a prefix is provided, the path will be prefixed by the prefix.

If the parent is equal to the provided child, the operation will return an empty string. If a nonzero component is provided, the path will be created by looking for parents with that component.

The returned path should be freed by the application.

Parameters

  world | The world.
  parent | The entity from which to create the path.
  child | The entity to which to create the path.
  sep | The separator to use between path elements.
  prefix | The initial character to use for root elements.

Returns
  The relative entity path.

See also
  ecs_get_path_w_sep_buf()

## ◆ ecs_get_path_w_sep_buf()

void ecs_get_path_w_sep_buf | ( | const ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | ecs_entity_t | child,
|  | const char * | sep,
|  | const char * | prefix,
|  | ecs_strbuf_t * | buf,
|  | bool | escape )

Write path identifier to buffer.

Same as ecs_get_path_w_sep(), but writes result to an ecs_strbuf_t.

Parameters

  world | The world.
  parent | The entity from which to create the path.
  child | The entity to which to create the path.
  sep | The separator to use between path elements.
  prefix | The initial character to use for root elements.
  buf | The buffer to write to.

See also
  ecs_get_path_w_sep()

## ◆ ecs_get_scope()

ecs_entity_t ecs_get_scope | ( | const ecs_world_t * | world | ) |

Get the current scope.

Get the scope set by ecs_set_scope(). If no scope is set, this operation will return 0.

Parameters

  world | The world.

Returns
  The current scope.

## ◆ ecs_get_symbol()

const char * ecs_get_symbol | ( | const ecs_world_t * | world,
|  | ecs_entity_t | entity )

Get the symbol of an entity.

This will return the symbol stored in (EcsIdentifier, EcsSymbol).

Parameters

  world | The world.
  entity | The entity.

Returns
  The type of the entity, NULL if the entity has no name.

See also
  ecs_set_symbol()

## ◆ ecs_lookup()

ecs_entity_t ecs_lookup | ( | const ecs_world_t * | world,
|  | const char * | path )

Lookup an entity by it's path.

This operation is equivalent to calling:

ecs_lookup_path_w_sep(world, 0, path, ".", NULL, true);
ecs_lookup_path_w_sep
ecs_entity_t ecs_lookup_path_w_sep(const ecs_world_t *world, ecs_entity_t parent, const char *path, const char *sep, const char *prefix, bool recursive)
Lookup an entity from a path.

Parameters

  world | The world.
  path | The entity path.

Returns
  The entity with the specified path, or 0 if no entity was found.

See also
  ecs_lookup_child()
  ecs_lookup_path_w_sep()
  ecs_lookup_symbol()

## ◆ ecs_lookup_child()

ecs_entity_t ecs_lookup_child | ( | const ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | const char * | name )

Lookup a child entity by name.

Returns an entity that matches the specified name. Only looks for entities in the provided parent. If no parent is provided, look in the current scope ( root if no scope is provided).

Parameters

  world | The world.
  parent | The parent for which to lookup the child.
  name | The entity name.

Returns
  The entity with the specified name, or 0 if no entity was found.

See also
  ecs_lookup()
  ecs_lookup_path_w_sep()
  ecs_lookup_symbol()

## ◆ ecs_lookup_path_w_sep()

ecs_entity_t ecs_lookup_path_w_sep | ( | const ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | const char * | path,
|  | const char * | sep,
|  | const char * | prefix,
|  | bool | recursive )

Lookup an entity from a path.

Lookup an entity from a provided path, relative to the provided parent. The operation will use the provided separator to tokenize the path expression. If the provided path contains the prefix, the search will start from the root.

If the entity is not found in the provided parent, the operation will continue to search in the parent of the parent, until the root is reached. If the entity is still not found, the lookup will search in the flecs.core scope. If the entity is not found there either, the function returns 0.

Parameters

  world | The world.
  parent | The entity from which to resolve the path.
  path | The path to resolve.
  sep | The path separator.
  prefix | The path prefix.
  recursive | Recursively traverse up the tree until entity is found.

Returns
  The entity if found, else 0.

See also
  ecs_lookup()
  ecs_lookup_child()
  ecs_lookup_symbol()

## ◆ ecs_lookup_symbol()

ecs_entity_t ecs_lookup_symbol | ( | const ecs_world_t * | world,
|  | const char * | symbol,
|  | bool | lookup_as_path,
|  | bool | recursive )

Lookup an entity by its symbol name.

This looks up an entity by symbol stored in (EcsIdentifier, EcsSymbol). The operation does not take into account hierarchies.

This operation can be useful to resolve, for example, a type by its C identifier, which does not include the Flecs namespacing.

Parameters

  world | The world.
  symbol | The symbol.
  lookup_as_path | If not found as a symbol, lookup as path.
  recursive | If looking up as path, recursively traverse up the tree.

Returns
  The entity if found, else 0.

See also
  ecs_lookup()
  ecs_lookup_child()
  ecs_lookup_path_w_sep()

## ◆ ecs_new_from_path_w_sep()

ecs_entity_t ecs_new_from_path_w_sep | ( | ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | const char * | path,
|  | const char * | sep,
|  | const char * | prefix )

Find or create entity from path.

This operation will find or create an entity from a path, and will create any intermediate entities if required. If the entity already exists, no entities will be created.

If the path starts with the prefix, then the entity will be created from the root scope.

Parameters

  world | The world.
  parent | The entity relative to which the entity should be created.
  path | The path to create the entity for.
  sep | The separator used in the path.
  prefix | The prefix used in the path.

Returns
  The entity.

## ◆ ecs_set_alias()

void ecs_set_alias | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | const char * | alias )

Set alias for entity.

An entity can be looked up using its alias from the root scope without providing the fully qualified name if its parent. An entity can only have a single alias.

The symbol is stored in (EcsIdentifier, EcsAlias).

Parameters

  world | The world.
  entity | The entity.
  alias | The alias.

## ◆ ecs_set_lookup_path()

ecs_entity_t * ecs_set_lookup_path | ( | ecs_world_t * | world,
|  | const ecs_entity_t * | lookup_path )

Set search path for lookup operations.

This operation accepts an array of entity ids that will be used as search scopes by lookup operations. The operation returns the current search path. It is good practice to restore the old search path.

The search path will be evaluated starting from the last element.

The default search path includes flecs.core. When a custom search path is provided it overwrites the existing search path. Operations that rely on looking up names from flecs.core without providing the namespace may fail if the custom search path does not include flecs.core (EcsFlecsCore).

The search path array is not copied into managed memory. The application must ensure that the provided array is valid for as long as it is used as the search path.

The provided array must be terminated with a 0 element. This enables an application to push/pop elements to an existing array without invoking the ecs_set_lookup_path() operation again.

Parameters

  world | The world.
  lookup_path | 0-terminated array with entity ids for the lookup path.

Returns
  Current lookup path array.

See also
  ecs_get_lookup_path()

## ◆ ecs_set_name()

ecs_entity_t ecs_set_name | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | const char * | name )

Set the name of an entity.

This will set or overwrite the name of an entity. If no entity is provided, a new entity will be created.

The name is stored in (EcsIdentifier, EcsName).

Parameters

  world | The world.
  entity | The entity.
  name | The name.

Returns
  The provided entity, or a new entity if 0 was provided.

See also
  ecs_get_name()

## ◆ ecs_set_name_prefix()

const char * ecs_set_name_prefix | ( | ecs_world_t * | world,
|  | const char * | prefix )

Set a name prefix for newly created entities.

This is a utility that lets C modules use prefixed names for C types and C functions, while using names for the entity names that do not have the prefix. The name prefix is currently only used by ECS_COMPONENT.

Parameters

  world | The world.
  prefix | The name prefix to use.

Returns
  The previous prefix.

## ◆ ecs_set_scope()

ecs_entity_t ecs_set_scope | ( | ecs_world_t * | world,
|  | ecs_entity_t | scope )

Set the current scope.

This operation sets the scope of the current stage to the provided entity. As a result new entities will be created in this scope, and lookups will be relative to the provided scope.

It is considered good practice to restore the scope to the old value.

Parameters

  world | The world.
  scope | The entity to use as scope.

Returns
  The previous scope.

See also
  ecs_get_scope()

## ◆ ecs_set_symbol()

ecs_entity_t ecs_set_symbol | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | const char * | symbol )

Set the symbol of an entity.

This will set or overwrite the symbol of an entity. If no entity is provided, a new entity will be created.

The symbol is stored in (EcsIdentifier, EcsSymbol).

Parameters

  world | The world.
  entity | The entity.
  symbol | The symbol.

Returns
  The provided entity, or a new entity if 0 was provided.

See also
  ecs_get_symbol()