Flecs v3.1
A fast entity component system (ECS) for C & C++
Loading...
Searching...
No Matches
Getting & Setting

Functions for getting/setting components. More...

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. More...
 
ecs_ref_t ecs_ref_init_id (const ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
 Create a component ref. More...
 
void * ecs_ref_get_id (const ecs_world_t *world, ecs_ref_t *ref, ecs_id_t id)
 Get component from ref. More...
 
void ecs_ref_update (const ecs_world_t *world, ecs_ref_t *ref)
 Update ref. More...
 
void * ecs_get_mut_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
 Get a mutable pointer to a component. More...
 
ecs_record_t * ecs_write_begin (ecs_world_t *world, ecs_entity_t entity)
 Begin exclusive write access to entity. More...
 
void ecs_write_end (ecs_record_t *record)
 End exclusive write access to entity. More...
 
const ecs_record_t * ecs_read_begin (ecs_world_t *world, ecs_entity_t entity)
 Begin read access to entity. More...
 
void ecs_read_end (const ecs_record_t *record)
 End read access to entity. More...
 
const void * ecs_record_get_id (ecs_world_t *world, const ecs_record_t *record, ecs_id_t id)
 Get component from entity record. More...
 
void * ecs_record_get_mut_id (ecs_world_t *world, ecs_record_t *record, ecs_id_t id)
 Same as ecs_record_get_id, but returns a mutable pointer. More...
 
void * ecs_emplace_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
 Emplace a component. More...
 
void ecs_modified_id (ecs_world_t *world, ecs_entity_t entity, ecs_id_t id)
 Signal that a component has been modified. More...
 
ecs_entity_t 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. More...
 

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 
)

Emplace a component.

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

Emplace can only be used if the entity does not yet have the component. If the entity has the component, the operation will fail.

Parameters
worldThe world.
entityThe entity.
idThe component to obtain.
Returns
The (uninitialized) 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.

Parameters
worldThe world.
entityThe entity.
idThe id of the component to get.
Returns
The component pointer, NULL if the entity does not have the component.

◆ ecs_get_mut_id()

void * ecs_get_mut_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 get_mut 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
worldThe world.
entityThe entity.
idThe entity id of the component to obtain.
Returns
The component pointer.

◆ 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 allows an application to signal to Flecs that a component has been modified. As a result, OnSet systems will be invoked.

This operation is commonly used together with ecs_get_mut.

Parameters
worldThe world.
entityThe entity.
idThe 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
worldThe world.
entityThe 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
recordRecord to the entity.

◆ ecs_record_get_id()

const void * ecs_record_get_id ( 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
worldThe world.
recordRecord to the entity.
idThe (component) id.
Returns
Pointer to component, or NULL if entity does not have the component.

◆ ecs_record_get_mut_id()

void * ecs_record_get_mut_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
worldThe world.
recordRecord to the entity.
idThe (component) id.
Returns
Pointer to component, or NULL if entity does not have 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
worldThe world.
refThe ref.
idThe 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
worldThe world.
entityThe entity.
idThe 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
worldThe world.
refThe ref.

◆ ecs_set_id()

ecs_entity_t 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_get_mut and ecs_modified.

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

Parameters
worldThe world.
entityThe entity.
idThe id of the component to set.
sizeThe size of the pointer to the value.
ptrThe pointer to the value.
Returns
The entity. A new entity if no entity was provided.

◆ 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
worldThe world.
entityThe 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
recordRecord to the entity.