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

Functions for working with events and observers. More...

Classes

struct  ecs_event_desc_t
 

Typedefs

typedef struct ecs_event_desc_t ecs_event_desc_t
 

Functions

void ecs_emit (ecs_world_t *world, ecs_event_desc_t *desc)
 Send event. More...
 
ecs_entity_t ecs_observer_init (ecs_world_t *world, const ecs_observer_desc_t *desc)
 Create observer. More...
 
bool ecs_observer_default_run_action (ecs_iter_t *it)
 Default run action for observer. More...
 
void * ecs_get_observer_ctx (const ecs_world_t *world, ecs_entity_t observer)
 
void * ecs_get_observer_binding_ctx (const ecs_world_t *world, ecs_entity_t observer)
 

Detailed Description

Functions for working with events and observers.

Function Documentation

◆ ecs_emit()

void ecs_emit ( ecs_world_t world,
ecs_event_desc_t desc 
)

Send event.

This sends an event to matching triggers & is the mechanism used by flecs itself to send OnAdd, OnRemove, etc events.

Applications can use this function to send custom events, where a custom event can be any regular entity.

Applications should not send builtin flecs events, as this may violate assumptions the code makes about the conditions under which those events are sent.

Triggers are invoked synchronously. It is therefore safe to use stack-based data as event context, which can be set in the "param" member.

To send a notification for a single entity, an application should set the following members in the event descriptor:

  • table: set to the table of the entity
  • offset: set to the row of the entity in the table
  • count: set to 1

The table & row of the entity can be obtained like this: ecs_record_t *r = ecs_record_find(world, e); desc.table = r->table; desc.offset = ECS_RECORD_TO_ROW(r->row);

Parameters
worldThe world.
descEvent parameters.

◆ ecs_observer_default_run_action()

bool ecs_observer_default_run_action ( ecs_iter_t *  it)

Default run action for observer.

This function can be called from a custom observer run action (see ecs_observer_desc_t::run for more details). This function ensures that the observer's filter is applied to the iterator's table, filters out duplicate events and implements EcsMonitor logic.

Parameters
itThe iterator.
Returns
True if the observer was invoked.

◆ ecs_observer_init()

ecs_entity_t ecs_observer_init ( ecs_world_t world,
const ecs_observer_desc_t desc 
)

Create observer.

Observers are like triggers, but can subscribe for multiple terms. An observer only triggers when the source of the event meets all terms.

See the documentation for ecs_observer_desc_t for more details.

Parameters
worldThe world.
descThe observer creation parameters.