Flecs: Getting & Setting
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
Getting & Setting
C API » Core » Entities

Functions for getting/setting components. More...

Collaboration diagram for Getting & Setting:

## Functions
const void * | ecs_get_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Get an immutable pointer to a component.
void * | ecs_get_mut_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Get a mutable pointer to a component.
void * | ecs_ensure_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Get a mutable pointer to a component.
void * | ecs_ensure_modified_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Combines ensure + modified in single operation.
ecs_ref_t | ecs_ref_init_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Create a component ref.
void * | ecs_ref_get_id (const ecs_world_t *world, ecs_ref_t *ref, ecs_id_t id)
| Get component from ref.
void | ecs_ref_update (const ecs_world_t *world, ecs_ref_t *ref)
| Update ref.
void * | ecs_emplace_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id, bool *is_new)
| Emplace a component.
void | ecs_modified_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
| Signal that a component has been modified.
void | ecs_set_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id, size_t size, const void *ptr)
| Set the value of a component.

## Detailed Description

Functions for getting/setting components.

## Function Documentation

## ◆ ecs_emplace_id()

void * ecs_emplace_id | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id,
|  | bool * | is_new )

Emplace a component.

Emplace is similar to ecs_ensure_id() except that the component constructor is not invoked for the returned pointer, allowing the component to be constructed directly in the storage.

When the `is_new` parameter is not provided, the operation will assert when the component already exists. When the `is_new` parameter is provided, it will indicate whether the returned storage has been constructed.

When `is_new` indicates that the storage has not yet been constructed, it must be constructed by the code invoking this operation. Not constructing the component will result in undefined behavior.

Parameters

  world | The world.
  entity | The entity.
  id | The component to obtain.
  is_new | Whether this is an existing or new component.

Returns
  The (uninitialized) component pointer.

## ◆ ecs_ensure_id()

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

Get a mutable pointer to a component.

This operation returns a mutable pointer to a component. If the component did not yet exist, it will be added.

If ensure is called when the world is in deferred/readonly mode, the function will:

- return a pointer to a temp storage if the component does not yet exist, or
- return a pointer to the existing component if it exists

Parameters

  world | The world.
  entity | The entity.
  id | The entity id of the component to obtain.

Returns
  The component pointer.

See also
  ecs_ensure_modified_id()
  ecs_emplace_id()

## ◆ ecs_ensure_modified_id()

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

Combines ensure + modified in single operation.

This operation is a more efficient alternative to calling ecs_ensure_id() and ecs_modified_id() separately. This operation is only valid when the world is in deferred mode, which ensures that the Modified event is not emitted before the modification takes place.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component to obtain.

Returns
  The component pointer.

## ◆ ecs_get_id()

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

Get an immutable pointer to a component.

This operation obtains a const pointer to the requested component. The operation accepts the component entity id.

This operation can return inherited components reachable through an `IsA` relationship.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component to get.

Returns
  The component pointer, NULL if the entity does not have the component.

See also
  ecs_get_mut_id()

## ◆ ecs_get_mut_id()

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

Get a mutable pointer to a component.

This operation obtains a mutable pointer to the requested component. The operation accepts the component entity id.

Unlike ecs_get_id(), this operation does not return inherited components.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component to get.

Returns
  The component pointer, NULL if the entity does not have the component.

## ◆ ecs_modified_id()

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

Signal that a component has been modified.

This operation is usually used after modifying a component value obtained by ecs_ensure_id(). The operation will mark the component as dirty, and invoke OnSet observers and hooks.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component that was modified.

## ◆ ecs_ref_get_id()

void * ecs_ref_get_id | ( | const ecs_world_t * | world,
|  | ecs_ref_t * | ref,
|  | ecs_id_t | id )

Get component from ref.

Get component pointer from ref. The ref must be created with ecs_ref_init().

Parameters

  world | The world.
  ref | The ref.
  id | The component id.

Returns
  The component pointer, NULL if the entity does not have the component.

## ◆ ecs_ref_init_id()

ecs_ref_t ecs_ref_init_id | ( | const ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id )

Create a component ref.

A ref is a handle to an entity + component which caches a small amount of data to reduce overhead of repeatedly accessing the component. Use ecs_ref_get() to get the component data.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component.

Returns
  The reference.

## ◆ ecs_ref_update()

void ecs_ref_update | ( | const ecs_world_t * | world,
|  | ecs_ref_t * | ref )

Update ref.

Ensures contents of ref are up to date. Same as ecs_ref_get_id(), but does not return pointer to component id.

Parameters

  world | The world.
  ref | The ref.

## ◆ ecs_set_id()

void ecs_set_id | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity,
|  | ecs_id_t | id,
|  | size_t | size,
|  | const void * | ptr )

Set the value of a component.

This operation allows an application to set the value of a component. The operation is equivalent to calling ecs_ensure_id() followed by ecs_modified_id(). The operation will not modify the value of the passed in component. If the component has a copy hook registered, it will be used to copy in the component.

If the provided entity is 0, a new entity will be created.

Parameters

  world | The world.
  entity | The entity.
  id | The id of the component to set.
  size | The size of the pointed-to value.
  ptr | The pointer to the value.