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

Functions for creating and deleting entities. More...

Functions

ecs_entity_t ecs_new_id (ecs_world_t *world)
 Create new entity id. More...
 
ecs_entity_t ecs_new_low_id (ecs_world_t *world)
 Create new low id. More...
 
ecs_entity_t ecs_new_w_id (ecs_world_t *world, ecs_id_t id)
 Create new entity with (component) id. More...
 
ecs_entity_t ecs_entity_init (ecs_world_t *world, const ecs_entity_desc_t *desc)
 Find or create an entity. More...
 
const ecs_entity_tecs_bulk_init (ecs_world_t *world, const ecs_bulk_desc_t *desc)
 Bulk create/populate new entities. More...
 
const ecs_entity_tecs_bulk_new_w_id (ecs_world_t *world, ecs_id_t id, int32_t count)
 Create N new entities. More...
 
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. More...
 
void ecs_delete (ecs_world_t *world, ecs_entity_t entity)
 Delete an entity. More...
 
void ecs_delete_with (ecs_world_t *world, ecs_id_t id)
 Delete all entities with the specified id. More...
 

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 datastructure 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 and does not recycle ids.

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.

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 recycled. Repeatedly calling ecs_delete without ecs_new or ecs_new_w_id will cause a memory leak as it will cause the list with ids that can be recycled to grow unbounded.

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 ECS_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 ECS_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 paramter, no component is added to the new entity.

Parameters
worldThe world.
idThe component id to initialize the new entity with.
Returns
The new entity.