Flecs v3.2
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Creating & Deleting

Functions for creating and deleting entities. More...

Collaboration diagram for Creating & Deleting:

Functions

ecs_entity_t ecs_new_id (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_tecs_bulk_init (ecs_world_t *world, const ecs_bulk_desc_t *desc)
 Bulk create/populate new entities.
 
const ecs_entity_tecs_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
worldThe world.
descBulk 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
worldThe world.
idThe component id to create the entities with.
countThe 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
worldThe world.
dstThe entity to copy the components to.
srcThe entity to copy the components from.
copy_valueIf 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
worldThe world.
entityThe 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
worldThe world.
idThe 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
worldThe world.
descEntity init parameters.
Returns
A handle to the new or existing entity, or 0 if failed.

◆ ecs_new_id()

ecs_entity_t ecs_new_id ( 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
worldThe 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
worldThe 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
worldThe world.
idThe 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
worldThe world.
tableThe table to which to add the new entity.
Returns
The new entity.