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

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.
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.