Entity Names

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

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.

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

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.

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.

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

Parameters

world	The world.
path	The entity path.

Returns

The entity with the specified path, 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

world	The world.
name	The 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

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.

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.

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.

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.

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.

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.