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.
ecs_record_t * | ecs_record_find (const ecs_world_t *world, ecs_entity_t entity)
| Find record for entity.
ecs_record_t * | ecs_write_begin (ecs_world_t *world, ecs_entity_t entity)
| Begin exclusive write access to entity.
void | ecs_write_end (ecs_record_t *record)
| End exclusive write access to entity.
const ecs_record_t * | ecs_read_begin (ecs_world_t *world, ecs_entity_t entity)
| Begin read access to entity.
void | ecs_read_end (const ecs_record_t *record)
| End read access to entity.
ecs_entity_t | ecs_record_get_entity (const ecs_record_t *record)
| Get entity corresponding with record.
const void * | ecs_record_get_id (const ecs_world_t *world, const ecs_record_t *record, ecs_id_t id)
| Get component from entity record.
void * | ecs_record_ensure_id (ecs_world_t *world, ecs_record_t *record, ecs_id_t id)
| Same as ecs_record_get_id(), but returns a mutable pointer.
bool | ecs_record_has_id (ecs_world_t *world, const ecs_record_t *record, ecs_id_t id)
| Test if entity for record has a (component) id.
void * | ecs_record_get_by_column (const ecs_record_t *record, int32_t column, size_t size)
| Get component pointer from column/record.
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_read_begin()

const ecs_record_t * ecs_read_begin | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity )

Begin read access to entity.

This operation provides safe read access to the components of an entity. Multiple simultaneous reads are allowed per entity.

This operation ensures that code attempting to mutate the entity's table will throw an assert. Note that for this to happen, asserts must be enabled. It is up to the application to ensure that this does not happen, for example by using a read-write mutex.

This operation does not provide the same guarantees as a read-write mutex, as it is possible to call ecs_read_begin() after calling ecs_write_begin(). It is up to application has to ensure that this does not happen.

This operation must be followed up with ecs_read_end().

Parameters

  world | The world.
  entity | The entity.

Returns
  A record to the entity.

## ◆ ecs_read_end()

void ecs_read_end | ( | const ecs_record_t * | record | ) |

End read access to entity.

This operation ends read access, and must be called after ecs_read_begin().

Parameters

  record | Record to the entity.

## ◆ ecs_record_ensure_id()

void * ecs_record_ensure_id | ( | ecs_world_t * | world,
|  | ecs_record_t * | record,
|  | ecs_id_t | id )

Same as ecs_record_get_id(), but returns a mutable pointer.

For safe access to the component, obtain the record with ecs_write_begin().

Parameters

  world | The world.
  record | Record to the entity.
  id | The (component) id.

Returns
  Pointer to component, or NULL if entity does not have the component.

## ◆ ecs_record_find()

ecs_record_t * ecs_record_find | ( | const ecs_world_t * | world,
|  | ecs_entity_t | entity )

Find record for entity.

An entity record contains the table and row for the entity.

Parameters

  world | The world.
  entity | The entity.

Returns
  The record, NULL if the entity does not exist.

## ◆ ecs_record_get_by_column()

void * ecs_record_get_by_column | ( | const ecs_record_t * | record,
|  | int32_t | column,
|  | size_t | size )

Get component pointer from column/record.

This returns a pointer to the component using a table column index. The table's column index can be found with ecs_table_get_column_index().

Usage:

ecs_record_t *r = ecs_record_find(world, entity);
int32_t column = ecs_table_get_column_index(world, table, ecs_id(Position));
Position *ptr = ecs_record_get_by_column(r, column, sizeof(Position));
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component id for EcsDocDescription.
ecs_record_get_by_column
void * ecs_record_get_by_column(const ecs_record_t *record, int32_t column, size_t size)
Get component pointer from column/record.
ecs_record_find
ecs_record_t * ecs_record_find(const ecs_world_t *world, ecs_entity_t entity)
Find record for entity.
ecs_table_get_column_index
int32_t ecs_table_get_column_index(const ecs_world_t *world, const ecs_table_t *table, ecs_id_t id)
Get column index for id.
ecs_record_t
Record for entity index.
Definition flecs.h:494

Parameters

  record | The record.
  column | The column index in the entity's table.
  size | The component size.

Returns
  The component pointer.

## ◆ ecs_record_get_entity()

ecs_entity_t ecs_record_get_entity | ( | const ecs_record_t * | record | ) |

Get entity corresponding with record.

This operation only works for entities that are not empty.

Parameters

  record | The record for which to obtain the entity id.

Returns
  The entity id for the record.

## ◆ ecs_record_get_id()

const void * ecs_record_get_id | ( | const ecs_world_t * | world,
|  | const ecs_record_t * | record,
|  | ecs_id_t | id )

Get component from entity record.

This operation returns a pointer to a component for the entity associated with the provided record. For safe access to the component, obtain the record with ecs_read_begin() or ecs_write_begin().

Obtaining a component from a record is faster than obtaining it from the entity handle, as it reduces the number of lookups required.

Parameters

  world | The world.
  record | Record to the entity.
  id | The (component) id.

Returns
  Pointer to component, or NULL if entity does not have the component.

See also
  ecs_record_ensure_id()

## ◆ ecs_record_has_id()

bool ecs_record_has_id | ( | ecs_world_t * | world,
|  | const ecs_record_t * | record,
|  | ecs_id_t | id )

Test if entity for record has a (component) id.

Parameters

  world | The world.
  record | Record to the entity.
  id | The (component) id.

Returns
  Whether the entity has the component.

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

## ◆ ecs_write_begin()

ecs_record_t * ecs_write_begin | ( | ecs_world_t * | world,
|  | ecs_entity_t | entity )

Begin exclusive write access to entity.

This operation provides safe exclusive access to the components of an entity without the overhead of deferring operations.

When this operation is called simultaneously for the same entity more than once it will throw an assert. Note that for this to happen, asserts must be enabled. It is up to the application to ensure that access is exclusive, for example by using a read-write mutex.

Exclusive access is enforced at the table level, so only one entity can be exclusively accessed per table. The exclusive access check is thread safe.

This operation must be followed up with ecs_write_end().

Parameters

  world | The world.
  entity | The entity.

Returns
  A record to the entity.

## ◆ ecs_write_end()

void ecs_write_end | ( | ecs_record_t * | record | ) |

End exclusive write access to entity.

This operation ends exclusive access, and must be called after ecs_write_begin().

Parameters

  record | Record to the entity.