Struct bevy::ecs::event::EventWriter

pub struct EventWriter<'w, E>
where E: Event,
{ /* private fields */ }
Expand description

Sends events of type T.

§Usage

EventWriters are usually declared as a SystemParam.


#[derive(Event)]
pub struct MyEvent; // Custom event type.
fn my_system(mut writer: EventWriter<MyEvent>) {
    writer.send(MyEvent);
}

§Observers

“Buffered” Events, such as those sent directly in Events or sent using EventWriter, do not automatically trigger any Observers watching for that event, as each Event has different requirements regarding if it will be triggered, and if so, when it will be triggered in the schedule.

§Concurrency

EventWriter param has ResMut<Events<T>> inside. So two systems declaring EventWriter<T> params for the same event type won’t be executed concurrently.

§Untyped events

EventWriter can only send events of one specific type, which must be known at compile-time. This is not a problem most of the time, but you may find a situation where you cannot know ahead of time every kind of event you’ll need to send. In this case, you can use the “type-erased event” pattern.

fn send_untyped(mut commands: Commands) {
    // Send an event of a specific type without having to declare that
    // type as a SystemParam.
    //
    // Effectively, we're just moving the type parameter from the /type/ to the /method/,
    // which allows one to do all kinds of clever things with type erasure, such as sending
    // custom events to unknown 3rd party plugins (modding API).
    //
    // NOTE: the event won't actually be sent until commands get applied during
    // apply_deferred.
    commands.add(|w: &mut World| {
        w.send_event(MyEvent);
    });
}

Note that this is considered non-idiomatic, and should only be used when EventWriter will not work.

Implementations§

§

impl<'w, E> EventWriter<'w, E>
where E: Event,

pub fn send(&mut self, event: E) -> EventId<E>

Sends an event, which can later be read by EventReaders. This method returns the ID of the sent event.

See Events for details.

Examples found in repository?
examples/ecs/send_and_receive_events.rs (line 63)
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
fn read_and_write_different_event_types(mut a: EventWriter<A>, mut b: EventReader<B>) {
    for _ in b.read() {}
    a.send(A);
}

/// A dummy event type.
#[derive(Debug, Clone, Event)]
struct DebugEvent {
    resend_from_param_set: bool,
    resend_from_local_event_reader: bool,
    times_sent: u8,
}

/// A system that sends all combinations of events.
fn send_events(mut events: EventWriter<DebugEvent>, frame_count: Res<FrameCount>) {
    println!("Sending events for frame {:?}", frame_count.0);

    events.send(DebugEvent {
        resend_from_param_set: false,
        resend_from_local_event_reader: false,
        times_sent: 1,
    });
    events.send(DebugEvent {
        resend_from_param_set: true,
        resend_from_local_event_reader: false,
        times_sent: 1,
    });
    events.send(DebugEvent {
        resend_from_param_set: false,
        resend_from_local_event_reader: true,
        times_sent: 1,
    });
    events.send(DebugEvent {
        resend_from_param_set: true,
        resend_from_local_event_reader: true,
        times_sent: 1,
    });
}

/// A system that prints all events sent since the last time this system ran.
///
/// Note that some events will be printed twice, because they were sent twice.
fn debug_events(mut events: EventReader<DebugEvent>) {
    for event in events.read() {
        println!("{:?}", event);
    }
}

/// A system that both sends and receives events using [`ParamSet`].
fn send_and_receive_param_set(
    mut param_set: ParamSet<(EventReader<DebugEvent>, EventWriter<DebugEvent>)>,
    frame_count: Res<FrameCount>,
) {
    println!(
        "Sending and receiving events for frame {} with a `ParamSet`",
        frame_count.0
    );

    // We must collect the events to resend, because we can't access the writer while we're iterating over the reader.
    let mut events_to_resend = Vec::new();

    // This is p0, as the first parameter in the `ParamSet` is the reader.
    for event in param_set.p0().read() {
        if event.resend_from_param_set {
            events_to_resend.push(event.clone());
        }
    }

    // This is p1, as the second parameter in the `ParamSet` is the writer.
    for mut event in events_to_resend {
        event.times_sent += 1;
        param_set.p1().send(event);
    }
}
More examples
Hide additional examples
examples/app/custom_loop.rs (line 38)
36
37
38
39
40
fn exit_system(input: Res<Input>, mut exit_event: EventWriter<AppExit>) {
    if input.0 == "exit" {
        exit_event.send(AppExit::Success);
    }
}
examples/async_tasks/external_source_external_thread.rs (line 52)
50
51
52
53
54
fn read_stream(receiver: Res<StreamReceiver>, mut events: EventWriter<StreamEvent>) {
    for from_stream in receiver.try_iter() {
        events.send(StreamEvent(from_stream));
    }
}
examples/ecs/event.rs (line 47)
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
fn deal_damage_over_time(
    time: Res<Time>,
    mut state: ResMut<DamageTimer>,
    mut events: EventWriter<DealDamage>,
) {
    if state.tick(time.delta()).finished() {
        // Events can be sent with 'send' and constructed just like any other object.
        events.send(DealDamage { amount: 10 });
    }
}

// This system mutates the 'DealDamage' events to apply some armor value
// It also sends an 'ArmorBlockedDamage' event if the value of 'DealDamage' is zero
//
// Events are mutated using an 'EventMutator<T>' by calling 'read'. This returns an iterator
// over all the &mut T that this system has not read yet. Note, you can have multiple
// 'EventReader', 'EventWriter', and 'EventMutator' in a given system, as long as the types (T) are different.
fn apply_armor_to_damage(
    mut dmg_events: EventMutator<DealDamage>,
    mut armor_events: EventWriter<ArmorBlockedDamage>,
) {
    for event in dmg_events.read() {
        event.amount -= 1;
        if event.amount <= 0 {
            // Zero-sized events can also be sent with 'send'
            armor_events.send(ArmorBlockedDamage);
        }
    }
}
examples/ecs/ecs_guide.rs (line 171)
164
165
166
167
168
169
170
171
172
173
174
175
176
fn game_over_system(
    game_rules: Res<GameRules>,
    game_state: Res<GameState>,
    mut app_exit_events: EventWriter<AppExit>,
) {
    if let Some(ref player) = game_state.winning_player {
        println!("{player} won the game!");
        app_exit_events.send(AppExit::Success);
    } else if game_state.current_round == game_rules.max_rounds {
        println!("Ran out of rounds. Nobody wins!");
        app_exit_events.send(AppExit::Success);
    }
}
examples/audio/pitch.rs (line 53)
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
fn keyboard_input_system(
    keyboard_input: Res<ButtonInput<KeyCode>>,
    mut frequency: ResMut<PitchFrequency>,
    mut events: EventWriter<PlayPitch>,
) {
    if keyboard_input.just_pressed(KeyCode::ArrowUp) {
        frequency.0 *= 2.0f32.powf(1.0 / 12.0);
    }
    if keyboard_input.just_pressed(KeyCode::ArrowDown) {
        frequency.0 /= 2.0f32.powf(1.0 / 12.0);
    }
    if keyboard_input.just_pressed(KeyCode::Space) {
        events.send(PlayPitch);
    }
}

pub fn send_batch( &mut self, events: impl IntoIterator<Item = E>, ) -> SendBatchIds<E>

Sends a list of events all at once, which can later be read by EventReaders. This is more efficient than sending each event individually. This method returns the IDs of the sent events.

See Events for details.

Examples found in repository?
examples/app/log_layers_ecs.rs (line 41)
36
37
38
39
40
41
42
fn transfer_log_events(
    receiver: NonSend<CapturedLogEvents>,
    mut log_events: EventWriter<LogEvent>,
) {
    // Make sure to use `try_iter()` and not `iter()` to prevent blocking.
    log_events.send_batch(receiver.try_iter());
}

pub fn send_default(&mut self) -> EventId<E>
where E: Default,

Sends the default value of the event. Useful when the event is an empty struct. This method returns the ID of the sent event.

See Events for details.

Examples found in repository?
examples/ecs/event.rs (line 84)
76
77
78
79
80
81
82
83
84
85
86
87
fn apply_damage_to_health(
    mut dmg_events: EventReader<DealDamage>,
    mut rcvd_events: EventWriter<DamageReceived>,
) {
    for event in dmg_events.read() {
        info!("Applying {} damage", event.amount);
        if event.amount > 0 {
            // Events with a 'Default' implementation can be sent with 'send_default'
            rcvd_events.send_default();
        }
    }
}
More examples
Hide additional examples
examples/games/breakout.rs (line 380)
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
fn check_for_collisions(
    mut commands: Commands,
    mut score: ResMut<Score>,
    mut ball_query: Query<(&mut Velocity, &Transform), With<Ball>>,
    collider_query: Query<(Entity, &Transform, Option<&Brick>), With<Collider>>,
    mut collision_events: EventWriter<CollisionEvent>,
) {
    let (mut ball_velocity, ball_transform) = ball_query.single_mut();

    for (collider_entity, collider_transform, maybe_brick) in &collider_query {
        let collision = ball_collision(
            BoundingCircle::new(ball_transform.translation.truncate(), BALL_DIAMETER / 2.),
            Aabb2d::new(
                collider_transform.translation.truncate(),
                collider_transform.scale.truncate() / 2.,
            ),
        );

        if let Some(collision) = collision {
            // Sends a collision event so that other systems can react to the collision
            collision_events.send_default();

            // Bricks should be despawned and increment the scoreboard on collision
            if maybe_brick.is_some() {
                commands.entity(collider_entity).despawn();
                **score += 1;
            }

            // Reflect the ball's velocity when it collides
            let mut reflect_x = false;
            let mut reflect_y = false;

            // Reflect only if the velocity is in the opposite direction of the collision
            // This prevents the ball from getting stuck inside the bar
            match collision {
                Collision::Left => reflect_x = ball_velocity.x > 0.0,
                Collision::Right => reflect_x = ball_velocity.x < 0.0,
                Collision::Top => reflect_y = ball_velocity.y < 0.0,
                Collision::Bottom => reflect_y = ball_velocity.y > 0.0,
            }

            // Reflect velocity on the x-axis if we hit something on the x-axis
            if reflect_x {
                ball_velocity.x = -ball_velocity.x;
            }

            // Reflect velocity on the y-axis if we hit something on the y-axis
            if reflect_y {
                ball_velocity.y = -ball_velocity.y;
            }
        }
    }
}

Trait Implementations§

§

impl<E> SystemParam for EventWriter<'_, E>
where E: Event,

§

type State = FetchState<E>

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

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

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

fn init_state( world: &mut World, system_meta: &mut SystemMeta, ) -> <EventWriter<'_, E> as SystemParam>::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 <EventWriter<'_, E> as SystemParam>::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

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

fn apply( state: &mut <EventWriter<'_, E> as SystemParam>::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 <EventWriter<'_, E> as SystemParam>::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

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

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

Creates a parameter to be passed into a SystemParamFunction. Read more
§

impl<'w, 's, E> ReadOnlySystemParam for EventWriter<'w, E>

Auto Trait Implementations§

§

impl<'w, E> Freeze for EventWriter<'w, E>

§

impl<'w, E> RefUnwindSafe for EventWriter<'w, E>
where E: RefUnwindSafe,

§

impl<'w, E> Send for EventWriter<'w, E>

§

impl<'w, E> Sync for EventWriter<'w, E>

§

impl<'w, E> Unpin for EventWriter<'w, E>

§

impl<'w, E> !UnwindSafe for EventWriter<'w, E>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
§

impl<T> DowncastSync for T
where T: Any + Send + Sync,

§

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

Convert Arc<Trait> (where Trait: Downcast) to Arc<Any>. Arc<Any> can then be further downcast into Arc<ConcreteType> where ConcreteType implements Trait.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<S> FromSample<S> for S

§

fn from_sample_(s: S) -> S

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

§

fn into_sample(self) -> T

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

§

fn to_sample_(self) -> U

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
§

impl<T> ConditionalSend for T
where T: Send,

§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,

§

impl<T> Settings for T
where T: 'static + Send + Sync,

§

impl<T> WasmNotSend for T
where T: Send,

§

impl<T> WasmNotSendSync for T
where T: WasmNotSend + WasmNotSync,

§

impl<T> WasmNotSync for T
where T: Sync,