Flecs v3.1
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Entity Names

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

Functions

const char * ecs_get_name (const ecs_world_t *world, ecs_entity_t entity)
 Get the name of an entity. More...
 
const char * ecs_get_symbol (const ecs_world_t *world, ecs_entity_t entity)
 Get the symbol of an entity. More...
 
ecs_entity_t ecs_set_name (ecs_world_t *world, ecs_entity_t entity, const char *name)
 Set the name of an entity. More...
 
ecs_entity_t ecs_set_symbol (ecs_world_t *world, ecs_entity_t entity, const char *symbol)
 Set the symbol of an entity. More...
 
void ecs_set_alias (ecs_world_t *world, ecs_entity_t entity, const char *alias)
 Set alias for entity. More...
 
ecs_entity_t ecs_lookup (const ecs_world_t *world, const char *name)
 Lookup an entity by name. More...
 
ecs_entity_t ecs_lookup_child (const ecs_world_t *world, ecs_entity_t parent, const char *name)
 Lookup a child entity by name. More...
 
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. More...
 
ecs_entity_t ecs_lookup_symbol (const ecs_world_t *world, const char *symbol, bool lookup_as_path)
 Lookup an entity by its symbol name. More...
 
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. More...
 
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)
 Write path identifier to buffer. More...
 
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. More...
 
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. More...
 
ecs_entity_t ecs_set_scope (ecs_world_t *world, ecs_entity_t scope)
 Set the current scope. More...
 
ecs_entity_t ecs_get_scope (const ecs_world_t *world)
 Get the current scope. More...
 
const char * ecs_set_name_prefix (ecs_world_t *world, const char *prefix)
 Set a name prefix for newly created entities. More...
 
ecs_entity_tecs_set_lookup_path (ecs_world_t *world, const ecs_entity_t *lookup_path)
 Set search path for lookup operations. More...
 
ecs_entity_tecs_get_lookup_path (const ecs_world_t *world)
 Get current lookup path. More...
 

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
worldThe world.
entityThe entity to which to add the path.
parentThe entity relative to which the entity should be created.
pathThe path to create the entity for.
sepThe separator used in the path.
prefixThe 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
worldThe 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
worldThe world.
entityThe entity.
Returns
The type of the entity, NULL if the entity has no 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
worldThe world.
parentThe entity from which to create the path.
childThe entity to which to create the path.
sepThe separator to use between path elements.
prefixThe initial character to use for root elements.
Returns
The relative entity path.

◆ 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 
)

Write path identifier to buffer.

Same as ecs_get_path_w_sep, but writes result to an ecs_strbuf_t.

Parameters
worldThe world.
parentThe entity from which to create the path.
childThe entity to which to create the path.
sepThe separator to use between path elements.
prefixThe initial character to use for root elements.
bufThe buffer to write to.

◆ 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
worldThe 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
worldThe world.
entityThe entity.
Returns
The type of the entity, NULL if the entity has no name.

◆ ecs_lookup()

ecs_entity_t ecs_lookup ( const ecs_world_t world,
const char *  name 
)

Lookup an entity by name.

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

Parameters
worldThe world.
nameThe entity name.
Returns
The entity with the specified name, or 0 if no entity was found.

◆ 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
worldThe world.
nameThe entity name.
Returns
The entity with the specified name, or 0 if no entity was found.

◆ 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
worldThe world.
parentThe entity from which to resolve the path.
pathThe path to resolve.
sepThe path separator.
prefixThe path prefix.
recursiveRecursively traverse up the tree until entity is found.
Returns
The entity if found, else 0.

◆ ecs_lookup_symbol()

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

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.

◆ 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
worldThe world.
parentThe entity relative to which the entity should be created.
pathThe path to create the entity for.
sepThe separator used in the path.
prefixThe 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
worldThe world.
entityThe entity.
aliasThe 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
worldThe world.
lookup_path0-terminated array with entity ids for the lookup path.
Returns
Current lookup path array.

◆ 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
worldThe world.
entityThe entity.
nameThe name.
Returns
The provided entity, or a new entity if 0 was provided.

◆ 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
worldThe world.
prefixThe 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
worldThe world.
scopeThe entity to use as scope.
Returns
The previous 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
worldThe world.
entityThe entity.
symbolThe symbol.
Returns
The provided entity, or a new entity if 0 was provided.