bevy_ecs/event/
writer.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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
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
135
use bevy_ecs::{
    event::{Event, EventId, Events, SendBatchIds},
    system::{ResMut, SystemParam},
};

/// Sends events of type `T`.
///
/// # Usage
///
/// `EventWriter`s are usually declared as a [`SystemParam`].
/// ```
/// # use bevy_ecs::prelude::*;
///
/// #[derive(Event)]
/// pub struct MyEvent; // Custom event type.
/// fn my_system(mut writer: EventWriter<MyEvent>) {
///     writer.write(MyEvent);
/// }
///
/// # bevy_ecs::system::assert_is_system(my_system);
/// ```
/// # Observers
///
/// "Buffered" Events, such as those sent directly in [`Events`] or written using [`EventWriter`], do _not_ automatically
/// trigger any [`Observer`]s 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>>`](Events) inside. So two systems declaring `EventWriter<T>` params
/// for the same event type won't be executed concurrently.
///
/// # Untyped events
///
/// `EventWriter` can only write 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.
///
/// ```
/// # use bevy_ecs::{prelude::*, event::Events};
/// # #[derive(Event)]
/// # pub struct MyEvent;
/// 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.queue(|w: &mut World| {
///         w.send_event(MyEvent);
///     });
/// }
/// ```
/// Note that this is considered *non-idiomatic*, and should only be used when `EventWriter` will not work.
///
/// [`Observer`]: crate::observer::Observer
#[derive(SystemParam)]
pub struct EventWriter<'w, E: Event> {
    #[system_param(validation_message = "Event not initialized")]
    events: ResMut<'w, Events<E>>,
}

impl<'w, E: Event> EventWriter<'w, E> {
    /// Writes an `event`, which can later be read by [`EventReader`](super::EventReader)s.
    /// This method returns the [ID](`EventId`) of the written `event`.
    ///
    /// See [`Events`] for details.
    #[doc(alias = "send")]
    #[track_caller]
    pub fn write(&mut self, event: E) -> EventId<E> {
        self.events.send(event)
    }

    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
    /// This is more efficient than sending each event individually.
    /// This method returns the [IDs](`EventId`) of the written `events`.
    ///
    /// See [`Events`] for details.
    #[doc(alias = "send_batch")]
    #[track_caller]
    pub fn write_batch(&mut self, events: impl IntoIterator<Item = E>) -> SendBatchIds<E> {
        self.events.send_batch(events)
    }

    /// Writes the default value of the event. Useful when the event is an empty struct.
    /// This method returns the [ID](`EventId`) of the written `event`.
    ///
    /// See [`Events`] for details.
    #[doc(alias = "send_default")]
    #[track_caller]
    pub fn write_default(&mut self) -> EventId<E>
    where
        E: Default,
    {
        self.events.send_default()
    }

    /// Sends an `event`, which can later be read by [`EventReader`](super::EventReader)s.
    /// This method returns the [ID](`EventId`) of the sent `event`.
    ///
    /// See [`Events`] for details.
    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write` instead.")]
    #[track_caller]
    pub fn send(&mut self, event: E) -> EventId<E> {
        self.write(event)
    }

    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
    /// This is more efficient than sending each event individually.
    /// This method returns the [IDs](`EventId`) of the sent `events`.
    ///
    /// See [`Events`] for details.
    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write_batch` instead.")]
    #[track_caller]
    pub fn send_batch(&mut self, events: impl IntoIterator<Item = E>) -> SendBatchIds<E> {
        self.write_batch(events)
    }

    /// Sends the default value of the event. Useful when the event is an empty struct.
    /// This method returns the [ID](`EventId`) of the sent `event`.
    ///
    /// See [`Events`] for details.
    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write_default` instead.")]
    #[track_caller]
    pub fn send_default(&mut self) -> EventId<E>
    where
        E: Default,
    {
        self.write_default()
    }
}