Flecs: Observers
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.1 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Observers
C API » Core

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

Collaboration diagram for Observers:

## Classes
struct | ecs_observer_desc_t
| Used with ecs_observer_init(). More...
struct | ecs_event_desc_t
| Used with ecs_emit(). More...

## Typedefs
typedef struct ecs_observer_desc_t | ecs_observer_desc_t
| Used with ecs_observer_init().
typedef struct ecs_event_desc_t | ecs_event_desc_t
| Used with ecs_emit().

## Functions
void | ecs_emit (ecs_world_t *world, ecs_event_desc_t *desc)
| Send an event.
void | ecs_enqueue (ecs_world_t *world, ecs_event_desc_t *desc)
| Enqueue an event.
ecs_entity_t | ecs_observer_init (ecs_world_t *world, const ecs_observer_desc_t *desc)
| Create an observer.
ecs_entity_t | ecs_observer_update (ecs_world_t *world, ecs_entity_t observer, const ecs_observer_desc_t *desc)
| Update an existing observer.
const ecs_observer_t * | ecs_observer_get (const ecs_world_t *world, ecs_entity_t observer)
| Get the observer object.

## 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 an event.

This sends an event to matching observers and 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 built-in Flecs events, as this may violate assumptions the code makes about the conditions under which those events are sent.

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

Parameters

  world | The world.
  desc | The event parameters.

See also
  ecs_enqueue()

## ◆ ecs_enqueue()

void ecs_enqueue | ( | ecs_world_t * | world,
|  | ecs_event_desc_t * | desc )

Enqueue an event.

Same as ecs_emit(), but enqueues an event in the command queue instead. The event will be emitted when ecs_defer_end() is called.

If this operation is called when the provided world is not in deferred mode, it behaves just like ecs_emit().

Parameters

  world | The world.
  desc | The event parameters.

## ◆ ecs_observer_get()

const ecs_observer_t * ecs_observer_get | ( | const ecs_world_t * | world,
|  | ecs_entity_t | observer )

Get the observer object.

Return the observer object. Can be used to access various information about the observer, like the query and context.

Parameters

  world | The world.
  observer | The observer.

Returns
  The observer object.

## ◆ ecs_observer_init()

ecs_entity_t ecs_observer_init | ( | ecs_world_t * | world,
|  | const ecs_observer_desc_t * | desc )

Create an observer.

Observers can subscribe for one or more terms. An observer only triggers when the source of the event meets all terms.

If the descriptor specifies an existing entity, the entity must not already be associated with an observer. To modify an existing observer, use ecs_observer_update().

See the documentation for ecs_observer_desc_t for more details.

Parameters

  world | The world.
  desc | The observer creation parameters.

Returns
  The observer, or 0 if the operation failed.

## ◆ ecs_observer_update()

ecs_entity_t ecs_observer_update | ( | ecs_world_t * | world,
|  | ecs_entity_t | observer,
|  | const ecs_observer_desc_t * | desc )

Update an existing observer.

Updates the configuration of an observer that was previously created with ecs_observer_init(). Only fields in desc that are set to a non-default value will be applied; fields left at their default value preserve the existing configuration of the observer.

The query and events fields of the descriptor are not used by this function; the observer query and event subscriptions cannot be modified after creation.

Parameters

  world | The world.
  observer | The observer to update.
  desc | The observer descriptor.

Returns
  The observer entity, or 0 if the operation failed.