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
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 component)
| Get an immutable pointer to a component.
void * | ecs_get_mut_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
| Get a mutable pointer to a component.
void * | ecs_ensure_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, size_t size)
| Ensure entity has component, return pointer.
ecs_ref_t | ecs_ref_init_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
| Create a component ref.
void * | ecs_ref_get_id (const ecs_world_t *world, ecs_ref_t *ref, ecs_id_t component)
| 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 component, size_t size, bool *is_new)
| Emplace a component.
void | ecs_modified_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t component)
| Signal that a component has been modified.
void | ecs_set_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t component, 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 | component,
|  | size_t | size,
|  | 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.
  component | The component to get/add.
  size | The component size.
  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 | component,
|  | size_t | size )

Ensure entity has component, return pointer.

This operation returns a mutable pointer to a component. If the entity did not yet have the component, 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.
  component | The component to get/add.

Returns
  The component pointer.

See also
  ecs_emplace_id()

## ◆ ecs_get_id()

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

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

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. This is to prevent errors where an application accidentally resolves an inherited component shared with many entities and modifies it, while thinking it is modifying an owned component.

Parameters

  world | The world.
  entity | The entity.
  component | 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 | component )

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

Get component from ref.

Get component pointer from ref. The ref must be created with ecs_ref_init(). The specified component must match the component with which the ref was created.

Parameters

  world | The world.
  ref | The ref.
  component | The component to get.

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

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.
  component | The component to create a ref for.

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 | component,
|  | 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.
  component | The component to set.
  size | The size of the pointed-to value.
  ptr | The pointer to the value.