Struct ObserverBuilder 

pub struct ObserverBuilder<'a, P = (), T: QueryTuple = ()> { /* private fields */ }

ObserverBuilder is used to configure and build Observers.

Observers are systems that react to events. Observers let applications register callbacks for ECS events.

These are typically constructed via World::observer().

Implementations

impl<'a, P: ComponentId, T: QueryTuple> ObserverBuilder<'a, P, T>

pub fn new_named(world: impl WorldProvider<'a>, name: &str) -> Self

Create a new observer builder with a name

Arguments

• world - The world to create the observer in
• name - The name of the observer

impl<P, T: QueryTuple> ObserverBuilder<'_, P, T>

pub fn set_observer_flags(&mut self, flags: ObserverFlags) -> &mut Self

set observer flags, which are the same as Query flags

Arguments

• flags - the flags to set

pub fn add_event( &mut self, event: impl IntoEntity, ) -> &mut ObserverBuilder<'_, (), T>

Specify the event(s) for when the observer should run.

Arguments

• event - The event to add

Examples found in repository

examples/flecs/observers/observer_basics.rs (line 27)

fn main() {
    let world = World::new();

    world
        .observer::<flecs::OnAdd, ()>()
        .with(Position::id())
        .each_iter(|it, index, _| {
            // We use .with(Position::id()) because we cannot safely access the component
            // value here. The component value is uninitialized when the OnAdd event
            // is emitted, which is UB in Rust. To work around this, we use .with::<T>
            println!(" - OnAdd: {}: {}", it.event_id().to_str(), it.entity(index));
        });

    // Create an observer for three events
    world
        .observer::<flecs::OnSet, &Position>()
        .add_event(flecs::OnRemove)
        .each_iter(|it, index, pos| {
            println!(
                " - {}: {}: {}: with {:?}",
                it.event().name(),
                it.event_id().to_str(),
                it.entity(index),
                pos
            );
        });

    // Create entity, set Position (emits EcsOnAdd and EcsOnSet)
    let entity = world.entity_named("e1").set(Position { x: 10.0, y: 20.0 });

    // Remove Position (emits EcsOnRemove)
    entity.remove(Position::id());

    // Remove Position again (no event emitted)
    entity.remove(Position::id());

    // Output:
    //  - OnAdd: Position: e1
    //  - OnSet: Position: e1: with Position { x: 10.0, y: 20.0 }
    //  - OnRemove: Position: e1: with Position { x: 10.0, y: 20.0 }
}

pub fn yield_existing(&mut self) -> &mut Self

Invoke observer for anything that matches its query on creation

Arguments

• should_yield - If true, the observer will be invoked for all existing entities that match its query

Examples found in repository

examples/flecs/observers/observer_yield_existing.rs (line 25)

fn main() {
    let world = World::new();

    // Create existing entities with Position component
    world.entity_named("e1").set(Position { x: 10.0, y: 20.0 });
    world.entity_named("e2").set(Position { x: 20.0, y: 30.0 });

    // Create an observer for three events
    world
        .observer::<flecs::OnSet, &Position>()
        .yield_existing()
        .each_iter(|it, index, pos| {
            println!(
                " - {}: {}: {}: {{ {}, {} }}",
                it.event().name(),
                it.event_id().to_str(),
                it.entity(index),
                pos.x,
                pos.y
            );
        });

    // Output:
    //  - OnSet: Position: e1: { 10, 20 }
    //  - OnSet: Position: e2: { 20, 30 }
}

Trait Implementations

impl<'a, P, T: QueryTuple> QueryBuilderImpl<'a> for ObserverBuilder<'a, P, T>

fn named(&mut self, name: &str) -> &mut Self

set the name of the query-like object

fn query_flags(&mut self, flags: QueryFlags) -> &mut Self

set querylags

fn set_cache_kind(&mut self, kind: QueryCacheKind) -> &mut Self

Set what cache method to use for the query

fn set_cached(&mut self) -> &mut Self

Set the cache method to cached

fn detect_changes(&mut self) -> &mut Self

fn expr(&mut self, expr: &'a str) -> &mut Self

set expression

fn with<T>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

fn with_enum<T: ComponentId + ComponentType<Enum> + EnumComponentInfo>( &mut self, value: T, ) -> &mut Self

set term with enum

fn with_enum_wildcard<T: ComponentType<Enum> + ComponentId>( &mut self, ) -> &mut Self

where (Id<T>, u64): InternalIntoEntity,

set term with enum wildcard

fn without<T>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

set term without Id

fn without_enum<T: ComponentId + ComponentType<Enum> + EnumComponentInfo>( &mut self, value: T, ) -> &mut Self

set term without enum

fn without_enum_wildcard<T: ComponentId + ComponentType<Enum> + EnumComponentInfo>( &mut self, ) -> &mut Self

where (Id<T>, u64): InternalIntoEntity,

set term without enum wildcard

fn term(&mut self) -> &mut Self

Term notation for more complex query features

fn term_at_type<T: ComponentId>(&mut self) -> &mut Self

Sets the current term to the one with the provided type. This loops over all terms to find the one with the provided type. For performance-critical paths, use term_at(index: u32) instead.

fn term_at(&mut self, index: u32) -> &mut Self

Sets the current term to the one at the provided index.

fn term_at_checked<T: ComponentId>(&mut self, index: u32) -> &mut Self

Set the current term to the one with the provided id and assert that the type matches. this does not do the type checking in release unless flecs_force_build_debug_c or flecs_force_enable_ecs_asserts is enabled.

fn write<T>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

Set the id as current term and in mode out

fn write_enum<T: ComponentId + ComponentType<Enum> + EnumComponentInfo>( &mut self, value: T, ) -> &mut Self

Set the type as current term and in mode out

fn read<T>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

Set the id as current term and in mode in

fn read_enum<T: ComponentId + ComponentType<Enum> + EnumComponentInfo>( &mut self, value: T, ) -> &mut Self

Set the type as current term and in mode in

fn scope_open(&mut self) -> &mut Self

Open a scope for the query

fn scope_close(&mut self) -> &mut Self

Close a scope for the query

fn order_by<T>(&mut self, compare: impl OrderByFn<T>) -> &mut Self

where T: ComponentId, Self: QueryBuilderImpl<'a>,

Sorts the output of a query.

fn order_by_id( &mut self, component: impl Into<Entity>, compare: impl OrderByFnVoid, ) -> &mut Self

Sorts the output of a query.

fn group_by_fn( &mut self, component: impl IntoEntity, group_by_action: ecs_group_by_action_t, ) -> &mut Self

Group and sort matched tables.

fn group_by(&mut self, component: impl IntoEntity) -> &mut Self

Group and sort matched tables.

fn group_by_ctx( &mut self, ctx: *mut c_void, ctx_free: ecs_ctx_free_t, ) -> &mut Self

Specify context to be passed to the group_by function.

fn on_group_create(&mut self, action: ecs_group_create_action_t) -> &mut Self

Specify the on_group_create action.

fn on_group_delete(&mut self, action: ecs_group_delete_action_t) -> &mut Self

Specify the on_group_delete action.

impl<'a, P, T> SystemAPI<'a, P, T> for ObserverBuilder<'a, P, T>

where T: QueryTuple, P: ComponentId,

fn set_context(&mut self, context: *mut c_void) -> &mut Self

Set context

fn each<Func>(&mut self, func: Func) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(T::TupleType<'_>) + 'static,

Each iterator for systems.

unsafe fn each_unchecked<Func>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(T::TupleType<'_>) + 'static,

Each iterator for systems without aliasing checks.

fn each_internal<Func, const CHECKED: bool>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(T::TupleType<'_>) + 'static,

Internal implementation for both checked and unchecked each iteration.

fn each_entity<Func>(&mut self, func: Func) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(EntityView<'_>, T::TupleType<'_>) + 'static,

Each entity iterator for systems.

unsafe fn each_entity_unchecked<Func>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(EntityView<'_>, T::TupleType<'_>) + 'static,

Each entity iterator for systems without aliasing checks.

fn each_entity_internal<Func, const CHECKED: bool>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(EntityView<'_>, T::TupleType<'_>) + 'static,

Internal implementation for both checked and unchecked each_entity iteration.

fn each_iter<Func>(&mut self, func: Func) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>) + 'static,

Each iterator. This variant of each provides access to the TableIter object, which contains more information about the object being iterated. The usize argument contains the index of the entity being iterated, which can be used to obtain entity-specific data from the TableIter object.

unsafe fn each_iter_unchecked<Func>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>) + 'static,

Unchecked version of each_iter that bypasses mutable aliasing checks.

fn each_iter_internal<Func, const CHECKED: bool>( &mut self, func: Func, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, false, P>, FieldIndex, T::TupleType<'_>) + 'static,

Internal implementation for each_iter and each_iter_unchecked.

fn run<Func>(&mut self, func: Func) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, true, P>) + 'static,

Run iterator. This operation expects manual iteration over the tables with iter.next() and iter.iter().

fn run_each<Func, FuncEach>( &mut self, func: Func, func_each: FuncEach, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, true, P>) + 'static, FuncEach: FnMut(T::TupleType<'_>) + 'static,

Run iterator with each forwarding. This operation expects manual iteration over the tables with iter.next() and iter.each()

fn run_each_entity<Func, FuncEachEntity>( &mut self, func: Func, func_each_entity: FuncEachEntity, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, true, P>) + 'static, FuncEachEntity: FnMut(EntityView<'_>, T::TupleType<'_>) + 'static,

Run iterator with each entity forwarding. This operation expects manual iteration over the tables with iter.next() and iter.each()

fn run_each_iter<Func, FuncEachIter>( &mut self, func: Func, func_each_iter: FuncEachIter, ) -> <Self as Builder<'a>>::BuiltType

where Func: FnMut(TableIter<'_, true, P>) + 'static, FuncEachIter: FnMut(TableIter<'_, true, P>, FieldIndex, T::TupleType<'_>) + 'static,

impl<'a, P, T: QueryTuple> TermBuilderImpl<'a> for ObserverBuilder<'a, P, T>

fn init_current_term<T>(&mut self, id: T)

where T: IntoId,

initializes a new term from a id of a component or pair

fn init_term_from<T: ComponentOrPairId>(&mut self)

initialize a new term from a component or pair

fn reset(&mut self)

Reset the term

fn is_set(&mut self) -> bool

Check if term is initialized

fn id(&self) -> Id

Get the term id of the current term set

fn inout(&self) -> InOutKind

Get the inout type of term of the current term set

fn oper(&self) -> OperKind

Get the operator of term of the current term set

fn src_id(&self) -> Entity

Get the src id of term of the current term set

fn first_id(&self) -> Entity

Get the first of term of the current term set

fn second_id(&self) -> Entity

Get the second of term of the current term set

fn self_(&mut self) -> &mut Self

The self flag indicates the term identifier itself is used

fn set_id(&mut self, id: impl IntoEntity) -> &mut Self

Specify value of identifier by id, same as id() of the current term set

fn entity(&mut self, entity: impl Into<Entity>) -> &mut Self

Specify value of identifier by id. Almost the same as id(entity), but this operation explicitly sets the flecs::IsEntity flag. This forces the id to be interpreted as entity, whereas not setting the flag would implicitly convert ids for builtin variables such as flecs::This to a variable.

fn name(&mut self, name: &'a str) -> &mut Self

Specify value of identifier by name

fn set_var(&mut self, var_name: &'a str) -> &mut Self

Specify identifier is a variable (resolved at query evaluation time)

fn flags(&mut self, flags: u64) -> &mut Self

Override term id flags

fn src(&mut self) -> &mut Self

Call prior to setting values for src identifier

fn first(&mut self) -> &mut Self

Call prior to setting values for first identifier. This is either the component identifier, or first element of a pair (in case second is populated as well).

fn second(&mut self) -> &mut Self

Call prior to setting values for second identifier. This is the second element of a pair. Requires that first() is populated as well.

fn set_src<T: SingleAccessArg>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

Select src identifier

fn set_first<Q: SingleAccessArg>(&mut self, id: Q) -> &mut Self

where Access: FromAccessArg<Q>,

Select first identifier

fn set_second<T: SingleAccessArg>(&mut self, id: T) -> &mut Self

where Access: FromAccessArg<T>,

Select second identifier

fn up(&mut self) -> &mut Self

default up where trav is set to 0. The up flag indicates that the term identifier may be substituted by traversing a relationship upwards. For example: substitute the identifier with its parent by traversing the ChildOf relationship.

fn parent(&mut self) -> &mut Self

same as up

fn up_id(&mut self, traverse_relationship: impl IntoEntity) -> &mut Self

The up flag indicates that the term identifier may be substituted by traversing a relationship upwards. For example: substitute the identifier with its parent by traversing the ChildOf relationship.

fn cascade(&mut self) -> &mut Self

Cascade iterates a hierarchy in top to bottom order (breadth first search) The cascade flag is like up, but returns results in breadth-first order. Only supported for flecs::query.

fn cascade_id(&mut self, traverse_relationship: impl IntoEntity) -> &mut Self

Cascade iterates a hierarchy in top to bottom order (breadth first search) The cascade flag is like up, but returns results in breadth-first order. Only supported for flecs::query

fn desc(&mut self) -> &mut Self

Use with cascade to iterate results in descending (bottom + top) order.

fn trav( &mut self, traverse_relationship: impl IntoEntity, flags: u64, ) -> &mut Self

Specify relationship to traverse, and flags to indicate direction

fn id_flags(&mut self, flags: impl IntoId) -> &mut Self

Set id flags for term.

fn set_inout_kind(&mut self, inout: InOutKind) -> &mut Self

Set read/write access of term

fn inout_stage(&mut self, inout: InOutKind) -> &mut Self

Set read/write access for stage. Use this when a system reads or writes components other than the ones provided by the query. This information can be used by schedulers to insert sync/merge points between systems where deferred operations are flushed.

fn write_curr(&mut self) -> &mut Self

Set write mode on current term. Short for inout_stage(InOutKind::Out). Use when system uses add, remove or set.

fn read_curr(&mut self) -> &mut Self

Set read mode on current term. Short for inout_stage(InOutKind::In). Use when system uses get

fn read_write_curr(&mut self) -> &mut Self

Short for inout_stage(InOutKind::InOut). Use when system uses ensure

fn set_in(&mut self) -> &mut Self

short for set_inout(InOutKind::In)

fn set_out(&mut self) -> &mut Self

short for set_inout(InOutKind::Out)

fn set_inout(&mut self) -> &mut Self

short for set_inout(InOutKind::InOut)

fn set_inout_none(&mut self) -> &mut Self

short for set_inout(InOutKind::None)

fn set_oper(&mut self, oper: OperKind) -> &mut Self

set operator of term

fn and(&mut self) -> &mut Self

short for set_oper(OperKind::And)

fn or(&mut self) -> &mut Self

short for set_oper(OperKind::Or)

fn not(&mut self) -> &mut Self

short for set_oper(OperKind::Not)

fn optional(&mut self) -> &mut Self

short for set_oper(OperKind::Optional)

fn and_from(&mut self) -> &mut Self

short for set_oper(OperKind::AndFrom)

fn or_from(&mut self) -> &mut Self

short for set_oper(OperKind::OrFrom)

fn not_from(&mut self) -> &mut Self

short for set_oper(OperKind::NotFrom)

fn filter(&mut self) -> &mut Self

Query terms are not triggered on by observers

impl<'a, P, T: QueryTuple> WorldProvider<'a> for ObserverBuilder<'a, P, T>

fn world(&self) -> WorldRef<'a>