bevy_ecs/event/
writer.rs

1use bevy_ecs::{
2    event::{Event, EventId, Events, SendBatchIds},
3    system::{ResMut, SystemParam},
4};
5
6/// Sends events of type `T`.
7///
8/// # Usage
9///
10/// `EventWriter`s are usually declared as a [`SystemParam`].
11/// ```
12/// # use bevy_ecs::prelude::*;
13///
14/// #[derive(Event)]
15/// pub struct MyEvent; // Custom event type.
16/// fn my_system(mut writer: EventWriter<MyEvent>) {
17///     writer.write(MyEvent);
18/// }
19///
20/// # bevy_ecs::system::assert_is_system(my_system);
21/// ```
22/// # Observers
23///
24/// "Buffered" Events, such as those sent directly in [`Events`] or written using [`EventWriter`], do _not_ automatically
25/// trigger any [`Observer`]s watching for that event, as each [`Event`] has different requirements regarding _if_ it will
26/// be triggered, and if so, _when_ it will be triggered in the schedule.
27///
28/// # Concurrency
29///
30/// `EventWriter` param has [`ResMut<Events<T>>`](Events) inside. So two systems declaring `EventWriter<T>` params
31/// for the same event type won't be executed concurrently.
32///
33/// # Untyped events
34///
35/// `EventWriter` can only write events of one specific type, which must be known at compile-time.
36/// This is not a problem most of the time, but you may find a situation where you cannot know
37/// ahead of time every kind of event you'll need to send. In this case, you can use the "type-erased event" pattern.
38///
39/// ```
40/// # use bevy_ecs::{prelude::*, event::Events};
41/// # #[derive(Event)]
42/// # pub struct MyEvent;
43/// fn send_untyped(mut commands: Commands) {
44///     // Send an event of a specific type without having to declare that
45///     // type as a SystemParam.
46///     //
47///     // Effectively, we're just moving the type parameter from the /type/ to the /method/,
48///     // which allows one to do all kinds of clever things with type erasure, such as sending
49///     // custom events to unknown 3rd party plugins (modding API).
50///     //
51///     // NOTE: the event won't actually be sent until commands get applied during
52///     // apply_deferred.
53///     commands.queue(|w: &mut World| {
54///         w.send_event(MyEvent);
55///     });
56/// }
57/// ```
58/// Note that this is considered *non-idiomatic*, and should only be used when `EventWriter` will not work.
59///
60/// [`Observer`]: crate::observer::Observer
61#[derive(SystemParam)]
62pub struct EventWriter<'w, E: Event> {
63    #[system_param(validation_message = "Event not initialized")]
64    events: ResMut<'w, Events<E>>,
65}
66
67impl<'w, E: Event> EventWriter<'w, E> {
68    /// Writes an `event`, which can later be read by [`EventReader`](super::EventReader)s.
69    /// This method returns the [ID](`EventId`) of the written `event`.
70    ///
71    /// See [`Events`] for details.
72    #[doc(alias = "send")]
73    #[track_caller]
74    pub fn write(&mut self, event: E) -> EventId<E> {
75        self.events.send(event)
76    }
77
78    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
79    /// This is more efficient than sending each event individually.
80    /// This method returns the [IDs](`EventId`) of the written `events`.
81    ///
82    /// See [`Events`] for details.
83    #[doc(alias = "send_batch")]
84    #[track_caller]
85    pub fn write_batch(&mut self, events: impl IntoIterator<Item = E>) -> SendBatchIds<E> {
86        self.events.send_batch(events)
87    }
88
89    /// Writes the default value of the event. Useful when the event is an empty struct.
90    /// This method returns the [ID](`EventId`) of the written `event`.
91    ///
92    /// See [`Events`] for details.
93    #[doc(alias = "send_default")]
94    #[track_caller]
95    pub fn write_default(&mut self) -> EventId<E>
96    where
97        E: Default,
98    {
99        self.events.send_default()
100    }
101
102    /// Sends an `event`, which can later be read by [`EventReader`](super::EventReader)s.
103    /// This method returns the [ID](`EventId`) of the sent `event`.
104    ///
105    /// See [`Events`] for details.
106    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write` instead.")]
107    #[track_caller]
108    pub fn send(&mut self, event: E) -> EventId<E> {
109        self.write(event)
110    }
111
112    /// Sends a list of `events` all at once, which can later be read by [`EventReader`](super::EventReader)s.
113    /// This is more efficient than sending each event individually.
114    /// This method returns the [IDs](`EventId`) of the sent `events`.
115    ///
116    /// See [`Events`] for details.
117    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write_batch` instead.")]
118    #[track_caller]
119    pub fn send_batch(&mut self, events: impl IntoIterator<Item = E>) -> SendBatchIds<E> {
120        self.write_batch(events)
121    }
122
123    /// Sends the default value of the event. Useful when the event is an empty struct.
124    /// This method returns the [ID](`EventId`) of the sent `event`.
125    ///
126    /// See [`Events`] for details.
127    #[deprecated(since = "0.16.0", note = "Use `EventWriter::write_default` instead.")]
128    #[track_caller]
129    pub fn send_default(&mut self) -> EventId<E>
130    where
131        E: Default,
132    {
133        self.write_default()
134    }
135}
bevy_ecs/event/writer.rs

bevy_ecs/event/
writer.rs
