Struct EventMutator

pub struct EventMutator<'w, 's, E: Event> { /* private fields */ }

Mutably reads events of type T keeping track of which events have already been read by each system allowing multiple systems to read the same events. Ideal for chains of systems that all want to modify the same events.

Usage

EventMutatorss are usually declared as a SystemParam.

#[derive(Event, Debug)]
pub struct MyEvent(pub u32); // Custom event type.
fn my_system(mut reader: EventMutator<MyEvent>) {
    for event in reader.read() {
        event.0 += 1;
        println!("received event: {:?}", event);
    }
}

Concurrency

Multiple systems with EventMutator<T> of the same event type can not run concurrently. They also can not be executed in parallel with EventReader or EventWriter.

Clearing, Reading, and Peeking

Events are stored in a double buffered queue that switches each frame. This switch also clears the previous frame’s events. Events should be read each frame otherwise they may be lost. For manual control over this behavior, see Events.

Most of the time systems will want to use EventMutator::read(). This function creates an iterator over all events that haven’t been read yet by this system, marking the event as read in the process.

Implementations

impl<'w, 's, E: Event> EventMutator<'w, 's, E>

pub fn read(&mut self) -> EventMutIterator<'_, E>

Iterates over the events this EventMutator has not seen yet. This updates the EventMutator’s event counter, which means subsequent event reads will not include events that happened before now.

pub fn read_with_id(&mut self) -> EventMutIteratorWithId<'_, E>

Like read, except also returning the EventId of the events.

pub fn len(&self) -> usize

Determines the number of events available to be read from this EventMutator without consuming any.

pub fn is_empty(&self) -> bool

Returns true if there are no events available to read.

Example

The following example shows a useful pattern where some behavior is triggered if new events are available. EventMutator::clear() is used so the same events don’t re-trigger the behavior the next time the system runs.

#[derive(Event)]
struct CollisionEvent;

fn play_collision_sound(mut events: EventMutator<CollisionEvent>) {
    if !events.is_empty() {
        events.clear();
        // Play a sound
    }
}

pub fn clear(&mut self)

Consumes all available events.

This means these events will not appear in calls to EventMutator::read() or EventMutator::read_with_id() and EventMutator::is_empty() will return true.

For usage, see EventMutator::is_empty().

Trait Implementations

impl<'w, 's, E: Debug + Event> Debug for EventMutator<'w, 's, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<E: Event> SystemParam for EventMutator<'_, '_, E>

type State = FetchState<E>

Used to store data which persists across invocations of a system.

type Item<'w, 's> = EventMutator<'w, 's, E>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World, system_meta: &mut SystemMeta) -> Self::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during apply_deferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next apply_deferred.

unsafe fn validate_param<'w, 's>( state: &'s Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, ) -> bool

Validates that the param can be acquired by the get_param. Built-in executors use this to prevent systems with invalid params from running. For nested SystemParams validation will fail if any delegated validation fails.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's, E: Event> ReadOnlySystemParam for EventMutator<'w, 's, E>

where Local<'s, EventCursor<E>>: ReadOnlySystemParam, ResMut<'w, Events<E>>: ReadOnlySystemParam,