Functions for creating and deleting entities. More...

Collaboration diagram for Creating & Deleting:

Functions
ecs_entity_t	ecs_new (ecs_world_t *world)
	Create new entity id.

ecs_entity_t	ecs_new_low_id (ecs_world_t *world)
	Create new low id.

ecs_entity_t	ecs_new_w_id (ecs_world_t *world, ecs_id_t id)
	Create new entity with (component) id.

ecs_entity_t	ecs_new_w_table (ecs_world_t world, ecs_table_t table)
	Create new entity in table.

ecs_entity_t	ecs_entity_init (ecs_world_t world, const ecs_entity_desc_t desc)
	Find or create an entity.

const ecs_entity_t *	ecs_bulk_init (ecs_world_t world, const ecs_bulk_desc_t desc)
	Bulk create/populate new entities.

const ecs_entity_t *	ecs_bulk_new_w_id (ecs_world_t *world, ecs_id_t id, int32_t count)
	Create N new entities.

ecs_entity_t	ecs_clone (ecs_world_t *world, ecs_entity_t dst, ecs_entity_t src, bool copy_value)
	Clone an entity This operation clones the components of one entity into another entity.

void	ecs_delete (ecs_world_t *world, ecs_entity_t entity)
	Delete an entity.

void	ecs_delete_with (ecs_world_t *world, ecs_id_t id)
	Delete all entities with the specified id.

Detailed Description

Functions for creating and deleting entities.

Function Documentation

◆ ecs_bulk_init()

const ecs_entity_t * ecs_bulk_init	(	ecs_world_t *	world,
		const ecs_bulk_desc_t *	desc )

Bulk create/populate new entities.

This operation bulk inserts a list of new or predefined entities into a single table.

The operation does not take ownership of component arrays provided by the application. Components that are non-trivially copyable will be moved into the storage.

The operation will emit OnAdd events for each added id, and OnSet events for each component that has been set.

If no entity ids are provided by the application, the returned array of ids points to an internal data structure which changes when new entities are created/deleted.

If as a result of the operation triggers are invoked that deletes entities and no entity ids were provided by the application, the returned array of identifiers may be incorrect. To avoid this problem, an application can first call ecs_bulk_init() to create empty entities, copy the array to one that is owned by the application, and then use this array to populate the entities.

Parameters

world	The world.
desc	Bulk creation parameters.

Returns: Array with the list of entity ids created/populated.

◆ ecs_bulk_new_w_id()

const ecs_entity_t * ecs_bulk_new_w_id	(	ecs_world_t *	world,
		ecs_id_t	id,
		int32_t	count )

Create N new entities.

This operation is the same as ecs_new_w_id(), but creates N entities instead of one.

Parameters

world	The world.
id	The component id to create the entities with.
count	The number of entities to create.

Returns: The first entity id of the newly created entities.

◆ ecs_clone()

ecs_entity_t ecs_clone	(	ecs_world_t *	world,
		ecs_entity_t	dst,
		ecs_entity_t	src,
		bool	copy_value )

Clone an entity This operation clones the components of one entity into another entity.

If no destination entity is provided, a new entity will be created. Component values are not copied unless copy_value is true.

If the source entity has a name, it will not be copied to the destination entity. This is to prevent having two entities with the same name under the same parent, which is not allowed.

Parameters

world	The world.
dst	The entity to copy the components to.
src	The entity to copy the components from.
copy_value	If true, the value of components will be copied to dst.

Returns: The destination entity.

◆ ecs_delete()

void ecs_delete	(	ecs_world_t *	world,
		ecs_entity_t	entity )

Delete an entity.

This operation will delete an entity and all of its components. The entity id will be made available for recycling. If the entity passed to ecs_delete() is not alive, the operation will have no side effects.

Parameters

world	The world.
entity	The entity.

◆ ecs_delete_with()

void ecs_delete_with	(	ecs_world_t *	world,
		ecs_id_t	id )

Delete all entities with the specified id.

This will delete all entities (tables) that have the specified id. The id may be a wildcard and/or a pair.

Parameters

world	The world.
id	The id.

◆ ecs_entity_init()

ecs_entity_t ecs_entity_init	(	ecs_world_t *	world,
		const ecs_entity_desc_t *	desc )

Find or create an entity.

This operation creates a new entity, or modifies an existing one. When a name is set in the ecs_entity_desc_t::name field and ecs_entity_desc_t::entity is not set, the operation will first attempt to find an existing entity by that name. If no entity with that name can be found, it will be created.

If both a name and entity handle are provided, the operation will check if the entity name matches with the provided name. If the names do not match, the function will fail and return 0.

If an id to a non-existing entity is provided, that entity id become alive.

See the documentation of ecs_entity_desc_t for more details.

Parameters

world	The world.
desc	Entity init parameters.

Returns: A handle to the new or existing entity, or 0 if failed.

◆ ecs_new()

ecs_entity_t ecs_new ( ecs_world_t * world )

Create new entity id.

This operation returns an unused entity id. This operation is guaranteed to return an empty entity as it does not use values set by ecs_set_scope() or ecs_set_with().

Parameters

world The world.

Returns: The new entity id.

◆ ecs_new_low_id()

ecs_entity_t ecs_new_low_id ( ecs_world_t * world )

Create new low id.

This operation returns a new low id. Entity ids start after the FLECS_HI_COMPONENT_ID constant. This reserves a range of low ids for things like components, and allows parts of the code to optimize operations.

Note that FLECS_HI_COMPONENT_ID does not represent the maximum number of components that can be created, only the maximum number of components that can take advantage of these optimizations.

This operation is guaranteed to return an empty entity as it does not use values set by ecs_set_scope() or ecs_set_with().

This operation does not recycle ids.

Parameters

world The world.

Returns: The new component id.

◆ ecs_new_w_id()

ecs_entity_t ecs_new_w_id	(	ecs_world_t *	world,
		ecs_id_t	id )

Create new entity with (component) id.

This operation creates a new entity with an optional (component) id. When 0 is passed to the id parameter, no component is added to the new entity.

Parameters

world	The world.
id	The component id to initialize the new entity with.

Returns: The new entity.

◆ ecs_new_w_table()

ecs_entity_t ecs_new_w_table	(	ecs_world_t *	world,
		ecs_table_t *	table )

Create new entity in table.

This operation creates a new entity in the specified table.

Parameters

world	The world.
table	The table to which to add the new entity.

Returns: The new entity.