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 auto override for 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.
ecs_entity_t	ecs_set_with (ecs_world_t *world, ecs_id_t component)
	Create new entities with specified component.
ecs_id_t	ecs_get_with (const ecs_world_t *world)
	Get component set with ecs_set_with().

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 auto override for 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_get_with()

ecs_id_t ecs_get_with

(

const ecs_world_t *

world

)

Get component set with ecs_set_with().

Get the component set with ecs_set_with().

Parameters

world

The world.

Returns

The last component provided to ecs_set_with().

See also

ecs_set_with()

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.

ecs_set_with()

ecs_entity_t ecs_set_with	(	ecs_world_t *	world,
		ecs_id_t	component )

Create new entities with specified component.

Entities created with ecs_entity_init() will be created with the specified component. This does not apply to entities created with ecs_new().

Only one component can be specified at a time. If this operation is called while a component is already configured, the new component will override the old component.

Parameters

world	The world.
component	The component.

Returns

The previously set component.

See also

ecs_entity_init()

ecs_set_with()