Adding & Removing

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 component)
	Add a (component) ID to an entity.
void	ecs_remove_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
	Remove a component from an entity.
void	ecs_auto_override_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
	Add an auto override for a component.
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 component)
	Remove all instances of the specified component.

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

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

ecs_auto_override_id()

void ecs_auto_override_id	(	ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_id_t	component )

Add an auto override for a component.

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

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);

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.
component	The component 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_remove_all()

void ecs_remove_all	(	ecs_world_t *	world,
		ecs_id_t	component )

Remove all instances of the specified component.

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

Parameters

world	The world.
component	The component.

ecs_remove_id()

void ecs_remove_id	(	ecs_world_t *	world,
		ecs_entity_t	entity,
		ecs_id_t	component )

Remove a component from an entity.

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

Parameters

world	The world.
entity	The entity.
component	The component to remove.