Flecs: Adding & Removing
Description: A fast entity component system (ECS) for C & C++

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

Loading...
Searching...
No Matches
Functions
Adding & Removing
C API » Core » Entities

Functions for adding and removing components. More...

Collaboration diagram for Adding & Removing:

## Functions
void | ecs_add_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Add a (component) id to an entity.
void | ecs_remove_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Remove a (component) id from an entity.
void | ecs_auto_override_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Add auto override for (component) id.
void | ecs_clear (ecs_world_t *world, ecs_entity_t entity)
| Clear all components.
void | ecs_remove_all (ecs_world_t *world, ecs_id_t id)
| Remove all instances of the specified (component) id.
ecs_entity_t | ecs_set_with (ecs_world_t *world, ecs_id_t id)
| Set current with id.
ecs_id_t | ecs_get_with (const ecs_world_t *world)
| Get current with id.

## Detailed Description

Functions for adding and removing components.

## Function Documentation

## ◆ ecs_add_id()

void ecs_add_id | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id )

Add a (component) id to an entity.

This operation adds a single (component) id to an entity. If the entity already has the id, this operation will have no side effects.

Parameters

  world | The world.
  entity | The entity.
  id | The id to add.

## ◆ ecs_auto_override_id()

void ecs_auto_override_id | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id )

Add auto override for (component) id.

An auto override is a component that is automatically added to an entity when it is instantiated from a prefab. Auto overrides are added to the entity that is inherited from (usually a prefab). For example:

ecs_entity_t prefab = ecs_insert(world,
ecs_value(Position, {10, 20}),
ecs_value(Mass, {100}));
ecs_auto_override(world, prefab, Position);
ecs_entity_t inst = ecs_new_w_pair(world, EcsIsA, prefab);
assert(ecs_owns(world, inst, Position)); // true
assert(ecs_owns(world, inst, Mass)); // false
EcsIsA
const ecs_entity_t EcsIsA
Used to express inheritance relationships.
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:347
ecs_value
#define ecs_value(T,...)
Convenience macro for creating compound literal value literal.
Definition flecs_c.h:738

An auto override is equivalent to a manual override:

ecs_entity_t prefab = ecs_insert(world,
ecs_value(Position, {10, 20}),
ecs_value(Mass, {100}));
ecs_entity_t inst = ecs_new_w_pair(world, EcsIsA, prefab);
assert(ecs_owns(world, inst, Position)); // false
ecs_add(world, inst, Position); // manual override
assert(ecs_owns(world, inst, Position)); // true
assert(ecs_owns(world, inst, Mass)); // false

This operation is equivalent to manually adding the id with the AUTO_OVERRIDE bit applied:

ecs_add_id(world, entity, ECS_AUTO_OVERRIDE | id);
ecs_add_id
void ecs_add_id(ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
Add a (component) id to an entity.
ECS_AUTO_OVERRIDE
const ecs_id_t ECS_AUTO_OVERRIDE
Automatically override component when it is inherited.

When a component is overridden and inherited from a prefab, the value from the prefab component is copied to the instance. When the component is not inherited from a prefab, it is added to the instance as if using ecs_add_id().

Overriding is the default behavior on prefab instantiation. Auto overriding is only useful for components with the `(OnInstantiate, Inherit)` trait. When a component has the `(OnInstantiate, DontInherit)` trait and is overridden the component is added, but the value from the prefab will not be copied.

Parameters

  world | The world.
  entity | The entity.
  id | The (component) id to auto override.

## ◆ ecs_clear()

void ecs_clear | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity )

Clear all components.

This operation will remove all components from an entity.

Parameters

  world | The world.
  entity | The entity.

## ◆ ecs_get_with()

ecs_id_t ecs_get_with | ( | const ecs_world_t * | world | ) |

Get current with id.

Get the id set with ecs_set_with().

Parameters

  world | The world.

Returns
  The last id provided to ecs_set_with().

## ◆ ecs_remove_all()

void ecs_remove_all | ( | ecs_world_t * | world,
|  | ecs_id_t | id )

Remove all instances of the specified (component) id.

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

Parameters

  world | The world.
  id | The id.

## ◆ ecs_remove_id()

void ecs_remove_id | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id )

Remove a (component) id from an entity.

This operation removes a single (component) id to an entity. If the entity does not have the id, this operation will have no side effects.

Parameters

  world | The world.
  entity | The entity.
  id | The id to remove.

## ◆ ecs_set_with()

ecs_entity_t ecs_set_with | ( | ecs_world_t * | world,
|  | ecs_id_t | id )

Set current with id.

New entities are automatically created with the specified id.

Parameters

  world | The world.
  id | The id.

Returns
  The previous id.