Flecs: Creating & Deleting
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Creating & Deleting
C API » Core » Entities

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 component)
| 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 or populate new entities.
const ecs_entity_t * | ecs_bulk_new_w_id (ecs_world_t *world, ecs_id_t component, 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.
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 component)
| Delete all entities with the specified component.
void | ecs_set_child_order (ecs_world_t *world, ecs_entity_t parent, const ecs_entity_t *children, int32_t child_count)
| Set child order for parent with OrderedChildren.
ecs_entities_t | ecs_get_ordered_children (const ecs_world_t *world, ecs_entity_t parent)
| Get ordered children.

## 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 or 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 or deleted.

If as a result of the operation, observers are invoked that delete 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
  An array with the list of entity IDs created or populated.

## ◆ ecs_bulk_new_w_id()

const ecs_entity_t * ecs_bulk_new_w_id | ( | ecs_world_t * | world,
|  | ecs_id_t | component,
|  | 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.
  component | The component to create the entities with.
  count | The number of entities to create.

Returns
  An array with the entity IDs 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 | component )

Delete all entities with the specified component.

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

Parameters

  world | The world.
  component | The component.

## ◆ 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 becomes 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_get_ordered_children()

ecs_entities_t ecs_get_ordered_children | ( | const ecs_world_t * | world,
|  | ecs_entity_t | parent )

Get ordered children.

If a parent has the OrderedChildren trait, this operation can be used to obtain the array with child entities. If this operation is used on a parent that does not have the OrderedChildren trait, it will fail.

Parameters

  world | The world.
  parent | The parent.

Returns
  The array with child entities.

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

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.
  component | The component to create 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.

## ◆ ecs_set_child_order()

void ecs_set_child_order | ( | ecs_world_t * | world,
|  | ecs_entity_t | parent,
|  | const ecs_entity_t * | children,
|  | int32_t | child_count )

Set child order for parent with OrderedChildren.

If the parent has the OrderedChildren trait, the order of the children will be updated to the order in the specified children array. The operation will fail if the parent does not have the OrderedChildren trait.

This operation always takes place immediately, and is not deferred. When the operation is called from a multithreaded system, it will fail.

The reason for not deferring this operation is that by the time the deferred command would be executed, the children of the parent could have been changed which would cause the operation to fail.

Parameters

  world | The world.
  parent | The parent.
  children | An array with children.
  child_count | The number of children in the provided array.