bevy_ecs/event/
mod.rs

1//! [`Event`] functionality.
2mod trigger;
3
4pub use bevy_ecs_macros::{EntityEvent, Event};
5pub use trigger::*;
6
7use crate::{
8    component::{Component, ComponentId},
9    entity::Entity,
10    world::World,
11};
12use core::marker::PhantomData;
13
14/// An [`Event`] is something that "happens" at a given moment.
15///
16/// To make an [`Event`] "happen", you "trigger" it on a [`World`] using [`World::trigger`] or via a [`Command`](crate::system::Command)
17/// using [`Commands::trigger`](crate::system::Commands::trigger). This causes any [`Observer`](crate::observer::Observer) watching for that
18/// [`Event`] to run _immediately_, as part of the [`World::trigger`] call.
19///
20/// First, we create an [`Event`] type, typically by deriving the trait.
21///
22/// ```
23/// # use bevy_ecs::prelude::*;
24/// #
25/// #[derive(Event)]
26/// struct Speak {
27///     message: String,
28/// }
29/// ```
30///
31/// Then, we add an [`Observer`](crate::observer::Observer) to watch for this event type:
32///
33/// ```
34/// # use bevy_ecs::prelude::*;
35/// #
36/// # #[derive(Event)]
37/// # struct Speak {
38/// #     message: String,
39/// # }
40/// #
41/// # let mut world = World::new();
42/// #
43/// world.add_observer(|speak: On<Speak>| {
44///     println!("{}", speak.message);
45/// });
46/// ```
47///
48/// Finally, we trigger the event by calling [`World::trigger`](World::trigger):
49///
50/// ```
51/// # use bevy_ecs::prelude::*;
52/// #
53/// # #[derive(Event)]
54/// # struct Speak {
55/// #     message: String,
56/// # }
57/// #
58/// # let mut world = World::new();
59/// #
60/// # world.add_observer(|speak: On<Speak>| {
61/// #     println!("{}", speak.message);
62/// # });
63/// #
64/// # world.flush();
65/// #
66/// world.trigger(Speak {
67///     message: "Hello!".to_string(),
68/// });
69/// ```
70///
71/// # Triggers
72///
73/// Every [`Event`] has an associated [`Trigger`] implementation (set via [`Event::Trigger`]), which defines which observers will run,
74/// what data will be passed to them, and the order they will be run in. Unless you are an internals developer or you have very specific
75/// needs, you don't need to worry too much about [`Trigger`]. When you derive [`Event`] (or a more specific event trait like [`EntityEvent`]),
76/// a [`Trigger`] will be provided for you.
77///
78/// The [`Event`] derive defaults [`Event::Trigger`] to [`GlobalTrigger`], which will run all observers that watch for the [`Event`].
79///
80/// # Entity Events
81///
82/// For events that "target" a specific [`Entity`], see [`EntityEvent`].
83#[diagnostic::on_unimplemented(
84    message = "`{Self}` is not an `Event`",
85    label = "invalid `Event`",
86    note = "consider annotating `{Self}` with `#[derive(Event)]`"
87)]
88pub trait Event: Send + Sync + Sized + 'static {
89    /// Defines which observers will run, what data will be passed to them, and the order they will be run in. See [`Trigger`] for more info.
90    type Trigger<'a>: Trigger<Self>;
91}
92
93/// An [`EntityEvent`] is an [`Event`] that is triggered for a specific [`EntityEvent::event_target`] entity:
94///
95/// ```
96/// # use bevy_ecs::prelude::*;
97/// # let mut world = World::default();
98/// # let entity = world.spawn_empty().id();
99/// #[derive(EntityEvent)]
100/// struct Explode {
101///     entity: Entity,
102/// }
103///
104/// world.add_observer(|event: On<Explode>, mut commands: Commands| {
105///     println!("Entity {} goes BOOM!", event.entity);
106///     commands.entity(event.entity).despawn();
107/// });
108///
109/// world.trigger(Explode { entity });
110/// ```
111///
112/// [`EntityEvent`] will set [`EntityEvent::event_target`] automatically for named structs with an `entity` field name (as seen above). It also works for tuple structs
113/// whose only field is [`Entity`]:
114///
115/// ```
116/// # use bevy_ecs::prelude::*;
117/// #[derive(EntityEvent)]
118/// struct Explode(Entity);
119/// ```
120///
121/// The [`EntityEvent::event_target`] can also be manually set using the `#[event_target]` field attribute:
122///
123/// ```
124/// # use bevy_ecs::prelude::*;
125/// #[derive(EntityEvent)]
126/// struct Explode {
127///     #[event_target]
128///     exploded_entity: Entity,
129/// }
130/// ```
131///
132/// ```
133/// # use bevy_ecs::prelude::*;
134/// #[derive(EntityEvent)]
135/// struct Explode(#[event_target] Entity);
136/// ```
137///
138/// You may also use any type which implements [`ContainsEntity`](crate::entity::ContainsEntity) as the event target:
139///
140/// ```
141/// # use bevy_ecs::prelude::*;
142/// struct Bomb(Entity);
143///
144/// impl ContainsEntity for Bomb {
145///     fn entity(&self) -> Entity {
146///         self.0
147///     }
148/// }
149///
150/// #[derive(EntityEvent)]
151/// struct Explode(Bomb);
152/// ```
153///
154/// By default, an [`EntityEvent`] is immutable. This means the event data, including the target, does not change while the event
155/// is triggered. However, to support event propagation, your event must also implement the [`SetEntityEventTarget`] trait.
156///
157/// This trait is automatically implemented for you if you enable event propagation:
158/// ```
159/// # use bevy_ecs::prelude::*;
160/// #[derive(EntityEvent)]
161/// #[entity_event(propagate)]
162/// struct Explode(Entity);
163/// ```
164///
165/// ## Trigger Behavior
166///
167/// When derived, [`EntityEvent`] defaults to setting [`Event::Trigger`] to [`EntityTrigger`], which will run all normal "untargeted"
168/// observers added via [`World::add_observer`], just like a default [`Event`] would (see the example above).
169///
170/// However it will _also_ run all observers that watch _specific_ entities, which enables you to assign entity-specific logic:
171///
172/// ```
173/// # use bevy_ecs::prelude::*;
174/// # #[derive(Component, Debug)]
175/// # struct Name(String);
176/// # let mut world = World::default();
177/// # let e1 = world.spawn_empty().id();
178/// # let e2 = world.spawn_empty().id();
179/// # #[derive(EntityEvent)]
180/// # struct Explode {
181/// #    entity: Entity,
182/// # }
183/// world.entity_mut(e1).observe(|event: On<Explode>, mut commands: Commands| {
184///     println!("Boom!");
185///     commands.entity(event.entity).despawn();
186/// });
187///
188/// world.entity_mut(e2).observe(|event: On<Explode>, mut commands: Commands| {
189///     println!("The explosion fizzles! This entity is immune!");
190/// });
191/// ```
192///
193/// ## [`EntityEvent`] Propagation
194///
195/// When deriving [`EntityEvent`], you can enable "event propagation" (also known as "event bubbling") by
196/// specifying the `#[entity_event(propagate)]` attribute:
197///
198/// ```
199/// # use bevy_ecs::prelude::*;
200/// #[derive(EntityEvent)]
201/// #[entity_event(propagate)]
202/// struct Click {
203///     entity: Entity,
204/// }
205/// ```
206///
207/// This will default to using the [`ChildOf`](crate::hierarchy::ChildOf) component to propagate the [`Event`] "up"
208/// the hierarchy (from child to parent).
209///
210/// You can also specify your own [`Traversal`](crate::traversal::Traversal) implementation. A common pattern is to use
211/// [`Relationship`](crate::relationship::Relationship) components, which will follow the relationships to their root
212/// (just be sure to avoid cycles ... these aren't detected for performance reasons):
213///
214/// ```
215/// # use bevy_ecs::prelude::*;
216/// #[derive(Component)]
217/// #[relationship(relationship_target = ClickableBy)]
218/// struct Clickable(Entity);
219///
220/// #[derive(Component)]
221/// #[relationship_target(relationship = Clickable)]
222/// struct ClickableBy(Vec<Entity>);
223///
224/// #[derive(EntityEvent)]
225/// #[entity_event(propagate = &'static Clickable)]
226/// struct Click {
227///     entity: Entity,
228/// }
229/// ```
230///
231/// By default, propagation requires observers to opt-in:
232///
233/// ```
234/// # use bevy_ecs::prelude::*;
235/// #[derive(EntityEvent)]
236/// #[entity_event(propagate)]
237/// struct Click {
238///     entity: Entity,
239/// }
240///
241/// # let mut world = World::default();
242/// world.add_observer(|mut click: On<Click>| {
243///   // this will propagate the event up to the parent, using `ChildOf`
244///   click.propagate(true);
245/// });
246/// ```
247///
248/// But you can enable auto propagation using the `#[entity_event(auto_propagate)]` attribute:
249/// ```
250/// # use bevy_ecs::prelude::*;
251/// #[derive(EntityEvent)]
252/// #[entity_event(propagate, auto_propagate)]
253/// struct Click {
254///     entity: Entity,
255/// }
256/// ```
257///
258/// You can also _stop_ propagation like this:
259/// ```
260/// # use bevy_ecs::prelude::*;
261/// # #[derive(EntityEvent)]
262/// # #[entity_event(propagate)]
263/// # struct Click {
264/// #    entity: Entity,
265/// # }
266/// # fn is_finished_propagating() -> bool { true }
267/// # let mut world = World::default();
268/// world.add_observer(|mut click: On<Click>| {
269///   if is_finished_propagating() {
270///     click.propagate(false);
271///   }
272/// });
273/// ```
274///
275/// ## Best practices for event propagation
276///
277/// Propagation is useful for events that should be handled by multiple entities in a hierarchy, such as UI events.
278/// In these cases, it is common for the event to be triggered on a "leaf" entity, and then propagate up to "root" entities.
279/// In this pattern, it is generally recommended to trigger the event on the most specific entity possible (the leaf), and then use propagation to have it handled by more general entities (the roots).
280///
281/// Once an event is handled by a given entity, you should stop propagation.
282/// This ensures that only a single "behavior" resolves per event sent,
283/// avoiding unexpected behavior from entities higher up the hierarchy.
284///
285/// This advice has one notable wrinkle:
286/// if an entity is "disabled" (e.g. if a UI node is grayed out),
287/// the event should still be considered "handled" by that entity,
288/// even though the observer logic should not be run.
289/// This ensures consistent behavior regardless of the enabled/disabled state of entities.
290///
291/// ## Naming and Usage Conventions
292///
293/// In most cases, it is recommended to use a named struct field for the "event target" entity, and to use
294/// a name that is descriptive as possible, as this makes events easier to understand and read.
295///
296/// For events with only one [`Entity`] field, `entity` is often a reasonable name. But if there are multiple
297/// [`Entity`] fields, it is often a good idea to use a more descriptive name.
298///
299/// It is also generally recommended to _consume_ "event target" entities directly via their named field, as this
300/// can make the context clearer, allows for more specific documentation hints in IDEs, and it generally reads better.
301///
302/// ## Manually spawning [`EntityEvent`] observers
303///
304/// The examples above that call [`EntityWorldMut::observe`] to add entity-specific observer logic are
305/// just shorthand for spawning an [`Observer`] directly and manually watching the entity:
306///
307/// ```
308/// # use bevy_ecs::prelude::*;
309/// # let mut world = World::default();
310/// # let entity = world.spawn_empty().id();
311/// # #[derive(EntityEvent)]
312/// # struct Explode(Entity);
313/// let mut observer = Observer::new(|event: On<Explode>| {});
314/// observer.watch_entity(entity);
315/// world.spawn(observer);
316/// ```
317///
318/// Note that the [`Observer`] component is not added to the entity it is observing. Observers should always be their own entities, as there
319/// can be multiple observers of the same entity!
320///
321/// You can call [`Observer::watch_entity`] more than once or [`Observer::watch_entities`] to watch multiple entities with the same [`Observer`].
322///
323/// [`EntityWorldMut::observe`]: crate::world::EntityWorldMut::observe
324/// [`Observer`]: crate::observer::Observer
325/// [`Observer::watch_entity`]: crate::observer::Observer::watch_entity
326/// [`Observer::watch_entities`]: crate::observer::Observer::watch_entities
327pub trait EntityEvent: Event {
328    /// The [`Entity`] "target" of this [`EntityEvent`]. When triggered, this will run observers that watch for this specific entity.
329    fn event_target(&self) -> Entity;
330}
331
332/// A trait which is used to set the target of an [`EntityEvent`].
333///
334/// By default, entity events are immutable; meaning their target does not change during the lifetime of the event. However, some events
335/// may require mutable access to provide features such as event propagation.
336///
337/// You should never need to implement this trait manually if you use `#[derive(EntityEvent)]`. It is automatically implemented for you if you
338/// use `#[entity_event(propagate)]`.
339pub trait SetEntityEventTarget: EntityEvent {
340    /// Sets the [`Entity`] "target" of this [`EntityEvent`]. When triggered, this will run observers that watch for this specific entity.
341    ///
342    /// Note: In general, this should not be called from within an [`Observer`](crate::observer::Observer), as this will not "retarget"
343    /// the event in any of Bevy's built-in [`Trigger`] implementations.
344    fn set_event_target(&mut self, entity: Entity);
345}
346
347impl World {
348    /// Generates the [`EventKey`] for this event type.
349    ///
350    /// If this type has already been registered,
351    /// this will return the existing [`EventKey`].
352    ///
353    /// This is used by various dynamically typed observer APIs,
354    /// such as [`DeferredWorld::trigger_raw`](crate::world::DeferredWorld::trigger_raw).
355    pub fn register_event_key<E: Event>(&mut self) -> EventKey {
356        EventKey(self.register_component::<EventWrapperComponent<E>>())
357    }
358
359    /// Fetches the [`EventKey`] for this event type,
360    /// if it has already been generated.
361    ///
362    /// This is used by various dynamically typed observer APIs,
363    /// such as [`DeferredWorld::trigger_raw`](crate::world::DeferredWorld::trigger_raw).
364    pub fn event_key<E: Event>(&self) -> Option<EventKey> {
365        self.component_id::<EventWrapperComponent<E>>()
366            .map(EventKey)
367    }
368}
369
370/// An internal type that implements [`Component`] for a given [`Event`] type.
371///
372/// This exists so we can easily get access to a unique [`ComponentId`] for each [`Event`] type,
373/// without requiring that [`Event`] types implement [`Component`] directly.
374/// [`ComponentId`] is used internally as a unique identifier for events because they are:
375///
376/// - Unique to each event type.
377/// - Can be quickly generated and looked up.
378/// - Are compatible with dynamic event types, which aren't backed by a Rust type.
379///
380/// This type is an implementation detail and should never be made public.
381// TODO: refactor events to store their metadata on distinct entities, rather than using `ComponentId`
382#[derive(Component)]
383struct EventWrapperComponent<E: Event>(PhantomData<E>);
384
385/// A unique identifier for an [`Event`], used by [observers].
386///
387/// You can look up the key for your event by calling the [`World::event_key`] method.
388///
389/// For dynamic events not backed by a Rust type, create an `EventKey` from
390/// a [`ComponentId`] using [`EventKey::new`]. Obtain a [`ComponentId`] via
391/// [`World::register_component_with_descriptor`].
392///
393/// [observers]: crate::observer
394#[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)]
395pub struct EventKey(pub(crate) ComponentId);
396
397impl EventKey {
398    /// Creates a new [`EventKey`] from a [`ComponentId`].
399    ///
400    /// Useful for dynamic events not backed by a Rust type. Obtain a
401    /// [`ComponentId`] via [`World::register_component_with_descriptor`].
402    ///
403    /// # Safety
404    ///
405    /// The caller must ensure that `component_id` was registered for use as
406    /// an event (e.g. via [`World::register_component_with_descriptor`]).
407    /// Using an unrelated [`ComponentId`] may cause observers to receive
408    /// data with an unexpected layout.
409    ///
410    /// [`World::register_component_with_descriptor`]: crate::world::World::register_component_with_descriptor
411    #[inline]
412    pub const unsafe fn new(component_id: ComponentId) -> Self {
413        Self(component_id)
414    }
415
416    /// Returns the underlying [`ComponentId`] for this event key.
417    #[inline]
418    pub const fn component_id(self) -> ComponentId {
419        self.0
420    }
421}
422
423#[cfg(test)]
424mod tests {
425    use alloc::{vec, vec::Vec};
426    use bevy_ecs::{message::*, system::assert_is_read_only_system};
427    use bevy_ecs_macros::Message;
428
429    #[derive(Message, Copy, Clone, PartialEq, Eq, Debug)]
430    struct TestEvent {
431        i: usize,
432    }
433
434    #[derive(Message, Clone, PartialEq, Debug, Default)]
435    struct EmptyTestEvent;
436
437    fn get_events<E: Message + Clone>(
438        events: &Messages<E>,
439        cursor: &mut MessageCursor<E>,
440    ) -> Vec<E> {
441        cursor.read(events).cloned().collect::<Vec<E>>()
442    }
443
444    #[test]
445    fn test_events() {
446        let mut events = Messages::<TestEvent>::default();
447        let event_0 = TestEvent { i: 0 };
448        let event_1 = TestEvent { i: 1 };
449        let event_2 = TestEvent { i: 2 };
450
451        // this reader will miss event_0 and event_1 because it wont read them over the course of
452        // two updates
453        let mut reader_missed: MessageCursor<TestEvent> = events.get_cursor();
454
455        let mut reader_a: MessageCursor<TestEvent> = events.get_cursor();
456
457        events.write(event_0);
458
459        assert_eq!(
460            get_events(&events, &mut reader_a),
461            vec![event_0],
462            "reader_a created before event receives event"
463        );
464        assert_eq!(
465            get_events(&events, &mut reader_a),
466            vec![],
467            "second iteration of reader_a created before event results in zero events"
468        );
469
470        let mut reader_b: MessageCursor<TestEvent> = events.get_cursor();
471
472        assert_eq!(
473            get_events(&events, &mut reader_b),
474            vec![event_0],
475            "reader_b created after event receives event"
476        );
477        assert_eq!(
478            get_events(&events, &mut reader_b),
479            vec![],
480            "second iteration of reader_b created after event results in zero events"
481        );
482
483        events.write(event_1);
484
485        let mut reader_c = events.get_cursor();
486
487        assert_eq!(
488            get_events(&events, &mut reader_c),
489            vec![event_0, event_1],
490            "reader_c created after two events receives both events"
491        );
492        assert_eq!(
493            get_events(&events, &mut reader_c),
494            vec![],
495            "second iteration of reader_c created after two event results in zero events"
496        );
497
498        assert_eq!(
499            get_events(&events, &mut reader_a),
500            vec![event_1],
501            "reader_a receives next unread event"
502        );
503
504        events.update();
505
506        let mut reader_d = events.get_cursor();
507
508        events.write(event_2);
509
510        assert_eq!(
511            get_events(&events, &mut reader_a),
512            vec![event_2],
513            "reader_a receives event created after update"
514        );
515        assert_eq!(
516            get_events(&events, &mut reader_b),
517            vec![event_1, event_2],
518            "reader_b receives events created before and after update"
519        );
520        assert_eq!(
521            get_events(&events, &mut reader_d),
522            vec![event_0, event_1, event_2],
523            "reader_d receives all events created before and after update"
524        );
525
526        events.update();
527
528        assert_eq!(
529            get_events(&events, &mut reader_missed),
530            vec![event_2],
531            "reader_missed missed events unread after two update() calls"
532        );
533    }
534
535    // Events Collection
536    fn events_clear_and_read_impl(clear_func: impl FnOnce(&mut Messages<TestEvent>)) {
537        let mut events = Messages::<TestEvent>::default();
538        let mut reader = events.get_cursor();
539
540        assert!(reader.read(&events).next().is_none());
541
542        events.write(TestEvent { i: 0 });
543        assert_eq!(*reader.read(&events).next().unwrap(), TestEvent { i: 0 });
544        assert_eq!(reader.read(&events).next(), None);
545
546        events.write(TestEvent { i: 1 });
547        clear_func(&mut events);
548        assert!(reader.read(&events).next().is_none());
549
550        events.write(TestEvent { i: 2 });
551        events.update();
552        events.write(TestEvent { i: 3 });
553
554        assert!(reader
555            .read(&events)
556            .eq([TestEvent { i: 2 }, TestEvent { i: 3 }].iter()));
557    }
558
559    #[test]
560    fn test_events_clear_and_read() {
561        events_clear_and_read_impl(Messages::clear);
562    }
563
564    #[test]
565    fn test_events_drain_and_read() {
566        events_clear_and_read_impl(|events| {
567            assert!(events
568                .drain()
569                .eq(vec![TestEvent { i: 0 }, TestEvent { i: 1 }].into_iter()));
570        });
571    }
572
573    #[test]
574    fn test_events_write_default() {
575        let mut events = Messages::<EmptyTestEvent>::default();
576        events.write_default();
577
578        let mut reader = events.get_cursor();
579        assert_eq!(get_events(&events, &mut reader), vec![EmptyTestEvent]);
580    }
581
582    #[test]
583    fn test_write_events_ids() {
584        let mut events = Messages::<TestEvent>::default();
585        let event_0 = TestEvent { i: 0 };
586        let event_1 = TestEvent { i: 1 };
587        let event_2 = TestEvent { i: 2 };
588
589        let event_0_id = events.write(event_0);
590
591        assert_eq!(
592            events.get_message(event_0_id.id),
593            Some((&event_0, event_0_id)),
594            "Getting a sent event by ID should return the original event"
595        );
596
597        let mut event_ids = events.write_batch([event_1, event_2]);
598
599        let event_id = event_ids.next().expect("Event 1 must have been sent");
600
601        assert_eq!(
602            events.get_message(event_id.id),
603            Some((&event_1, event_id)),
604            "Getting a sent event by ID should return the original event"
605        );
606
607        let event_id = event_ids.next().expect("Event 2 must have been sent");
608
609        assert_eq!(
610            events.get_message(event_id.id),
611            Some((&event_2, event_id)),
612            "Getting a sent event by ID should return the original event"
613        );
614
615        assert!(
616            event_ids.next().is_none(),
617            "Only sent two events; got more than two IDs"
618        );
619    }
620
621    #[test]
622    fn test_event_registry_can_add_and_remove_events_to_world() {
623        use bevy_ecs::prelude::*;
624
625        let mut world = World::new();
626        MessageRegistry::register_message::<TestEvent>(&mut world);
627
628        let has_events = world.get_resource::<Messages<TestEvent>>().is_some();
629        assert!(has_events, "Should have the events resource");
630
631        MessageRegistry::deregister_messages::<TestEvent>(&mut world);
632
633        let has_events = world.get_resource::<Messages<TestEvent>>().is_some();
634        assert!(!has_events, "Should not have the events resource");
635    }
636
637    #[test]
638    fn test_events_update_drain() {
639        let mut events = Messages::<TestEvent>::default();
640        let mut reader = events.get_cursor();
641
642        events.write(TestEvent { i: 0 });
643        events.write(TestEvent { i: 1 });
644        assert_eq!(reader.read(&events).count(), 2);
645
646        let mut old_events = Vec::from_iter(events.update_drain());
647        assert!(old_events.is_empty());
648
649        events.write(TestEvent { i: 2 });
650        assert_eq!(reader.read(&events).count(), 1);
651
652        old_events.extend(events.update_drain());
653        assert_eq!(old_events.len(), 2);
654
655        old_events.extend(events.update_drain());
656        assert_eq!(
657            old_events,
658            &[TestEvent { i: 0 }, TestEvent { i: 1 }, TestEvent { i: 2 }]
659        );
660    }
661
662    #[test]
663    fn test_events_empty() {
664        let mut events = Messages::<TestEvent>::default();
665        assert!(events.is_empty());
666
667        events.write(TestEvent { i: 0 });
668        assert!(!events.is_empty());
669
670        events.update();
671        assert!(!events.is_empty());
672
673        // events are only empty after the second call to update
674        // due to double buffering.
675        events.update();
676        assert!(events.is_empty());
677    }
678
679    #[test]
680    fn test_events_extend_impl() {
681        let mut events = Messages::<TestEvent>::default();
682        let mut reader = events.get_cursor();
683
684        events.extend(vec![TestEvent { i: 0 }, TestEvent { i: 1 }]);
685        assert!(reader
686            .read(&events)
687            .eq([TestEvent { i: 0 }, TestEvent { i: 1 }].iter()));
688    }
689
690    // Cursor
691    #[test]
692    fn test_event_cursor_read() {
693        let mut events = Messages::<TestEvent>::default();
694        let mut cursor = events.get_cursor();
695        assert!(cursor.read(&events).next().is_none());
696
697        events.write(TestEvent { i: 0 });
698        let sent_event = cursor.read(&events).next().unwrap();
699        assert_eq!(sent_event, &TestEvent { i: 0 });
700        assert!(cursor.read(&events).next().is_none());
701
702        events.write(TestEvent { i: 2 });
703        let sent_event = cursor.read(&events).next().unwrap();
704        assert_eq!(sent_event, &TestEvent { i: 2 });
705        assert!(cursor.read(&events).next().is_none());
706
707        events.clear();
708        assert!(cursor.read(&events).next().is_none());
709    }
710
711    #[test]
712    fn test_event_cursor_read_mut() {
713        let mut events = Messages::<TestEvent>::default();
714        let mut write_cursor = events.get_cursor();
715        let mut read_cursor = events.get_cursor();
716        assert!(write_cursor.read_mut(&mut events).next().is_none());
717        assert!(read_cursor.read(&events).next().is_none());
718
719        events.write(TestEvent { i: 0 });
720        let sent_event = write_cursor.read_mut(&mut events).next().unwrap();
721        assert_eq!(sent_event, &mut TestEvent { i: 0 });
722        *sent_event = TestEvent { i: 1 }; // Mutate whole event
723        assert_eq!(
724            read_cursor.read(&events).next().unwrap(),
725            &TestEvent { i: 1 }
726        );
727        assert!(read_cursor.read(&events).next().is_none());
728
729        events.write(TestEvent { i: 2 });
730        let sent_event = write_cursor.read_mut(&mut events).next().unwrap();
731        assert_eq!(sent_event, &mut TestEvent { i: 2 });
732        sent_event.i = 3; // Mutate sub value
733        assert_eq!(
734            read_cursor.read(&events).next().unwrap(),
735            &TestEvent { i: 3 }
736        );
737        assert!(read_cursor.read(&events).next().is_none());
738
739        events.clear();
740        assert!(write_cursor.read(&events).next().is_none());
741        assert!(read_cursor.read(&events).next().is_none());
742    }
743
744    #[test]
745    fn test_event_cursor_clear() {
746        let mut events = Messages::<TestEvent>::default();
747        let mut reader = events.get_cursor();
748
749        events.write(TestEvent { i: 0 });
750        assert_eq!(reader.len(&events), 1);
751        reader.clear(&events);
752        assert_eq!(reader.len(&events), 0);
753    }
754
755    #[test]
756    fn test_event_cursor_len_update() {
757        let mut events = Messages::<TestEvent>::default();
758        events.write(TestEvent { i: 0 });
759        events.write(TestEvent { i: 0 });
760        let reader = events.get_cursor();
761        assert_eq!(reader.len(&events), 2);
762        events.update();
763        events.write(TestEvent { i: 0 });
764        assert_eq!(reader.len(&events), 3);
765        events.update();
766        assert_eq!(reader.len(&events), 1);
767        events.update();
768        assert!(reader.is_empty(&events));
769    }
770
771    #[test]
772    fn test_event_cursor_len_current() {
773        let mut events = Messages::<TestEvent>::default();
774        events.write(TestEvent { i: 0 });
775        let reader = events.get_cursor_current();
776        assert!(reader.is_empty(&events));
777        events.write(TestEvent { i: 0 });
778        assert_eq!(reader.len(&events), 1);
779        assert!(!reader.is_empty(&events));
780    }
781
782    #[test]
783    fn test_event_cursor_iter_len_updated() {
784        let mut events = Messages::<TestEvent>::default();
785        events.write(TestEvent { i: 0 });
786        events.write(TestEvent { i: 1 });
787        events.write(TestEvent { i: 2 });
788        let mut reader = events.get_cursor();
789        let mut iter = reader.read(&events);
790        assert_eq!(iter.len(), 3);
791        iter.next();
792        assert_eq!(iter.len(), 2);
793        iter.next();
794        assert_eq!(iter.len(), 1);
795        iter.next();
796        assert_eq!(iter.len(), 0);
797    }
798
799    #[test]
800    fn test_event_cursor_len_empty() {
801        let events = Messages::<TestEvent>::default();
802        assert_eq!(events.get_cursor().len(&events), 0);
803        assert!(events.get_cursor().is_empty(&events));
804    }
805
806    #[test]
807    fn test_event_cursor_len_filled() {
808        let mut events = Messages::<TestEvent>::default();
809        events.write(TestEvent { i: 0 });
810        assert_eq!(events.get_cursor().len(&events), 1);
811        assert!(!events.get_cursor().is_empty(&events));
812    }
813
814    #[cfg(feature = "multi_threaded")]
815    #[test]
816    fn test_event_cursor_par_read() {
817        use crate::prelude::*;
818        use core::sync::atomic::{AtomicUsize, Ordering};
819
820        #[derive(Resource)]
821        struct Counter(AtomicUsize);
822
823        let mut world = World::new();
824        world.init_resource::<Messages<TestEvent>>();
825        for _ in 0..100 {
826            world.write_message(TestEvent { i: 1 });
827        }
828
829        let mut schedule = Schedule::default();
830
831        schedule.add_systems(
832            |mut cursor: Local<MessageCursor<TestEvent>>,
833             events: Res<Messages<TestEvent>>,
834             counter: ResMut<Counter>| {
835                cursor.par_read(&events).for_each(|event| {
836                    counter.0.fetch_add(event.i, Ordering::Relaxed);
837                });
838            },
839        );
840
841        world.insert_resource(Counter(AtomicUsize::new(0)));
842        schedule.run(&mut world);
843        let counter = world.remove_resource::<Counter>().unwrap();
844        assert_eq!(counter.0.into_inner(), 100);
845
846        world.insert_resource(Counter(AtomicUsize::new(0)));
847        schedule.run(&mut world);
848        let counter = world.remove_resource::<Counter>().unwrap();
849        assert_eq!(
850            counter.0.into_inner(),
851            0,
852            "par_read should have consumed events but didn't"
853        );
854    }
855
856    #[cfg(feature = "multi_threaded")]
857    #[test]
858    fn test_event_cursor_par_read_mut() {
859        use crate::prelude::*;
860        use core::sync::atomic::{AtomicUsize, Ordering};
861
862        #[derive(Resource)]
863        struct Counter(AtomicUsize);
864
865        let mut world = World::new();
866        world.init_resource::<Messages<TestEvent>>();
867        for _ in 0..100 {
868            world.write_message(TestEvent { i: 1 });
869        }
870        let mut schedule = Schedule::default();
871        schedule.add_systems(
872            |mut cursor: Local<MessageCursor<TestEvent>>,
873             mut events: ResMut<Messages<TestEvent>>,
874             counter: ResMut<Counter>| {
875                cursor.par_read_mut(&mut events).for_each(|event| {
876                    event.i += 1;
877                    counter.0.fetch_add(event.i, Ordering::Relaxed);
878                });
879            },
880        );
881        world.insert_resource(Counter(AtomicUsize::new(0)));
882        schedule.run(&mut world);
883        let counter = world.remove_resource::<Counter>().unwrap();
884        assert_eq!(counter.0.into_inner(), 200, "Initial run failed");
885
886        world.insert_resource(Counter(AtomicUsize::new(0)));
887        schedule.run(&mut world);
888        let counter = world.remove_resource::<Counter>().unwrap();
889        assert_eq!(
890            counter.0.into_inner(),
891            0,
892            "par_read_mut should have consumed events but didn't"
893        );
894    }
895
896    // Reader & Mutator
897    #[test]
898    fn ensure_reader_readonly() {
899        fn reader_system(_: MessageReader<EmptyTestEvent>) {}
900
901        assert_is_read_only_system(reader_system);
902    }
903
904    #[test]
905    fn test_event_reader_iter_last() {
906        use bevy_ecs::prelude::*;
907
908        let mut world = World::new();
909        world.init_resource::<Messages<TestEvent>>();
910
911        let mut reader = IntoSystem::into_system(
912            |mut events: MessageReader<TestEvent>| -> Option<TestEvent> {
913                events.read().last().copied()
914            },
915        );
916        reader.initialize(&mut world);
917
918        let last = reader.run((), &mut world).unwrap();
919        assert!(last.is_none(), "MessageReader should be empty");
920
921        world.write_message(TestEvent { i: 0 });
922        let last = reader.run((), &mut world).unwrap();
923        assert_eq!(last, Some(TestEvent { i: 0 }));
924
925        world.write_message(TestEvent { i: 1 });
926        world.write_message(TestEvent { i: 2 });
927        world.write_message(TestEvent { i: 3 });
928        let last = reader.run((), &mut world).unwrap();
929        assert_eq!(last, Some(TestEvent { i: 3 }));
930
931        let last = reader.run((), &mut world).unwrap();
932        assert!(last.is_none(), "MessageReader should be empty");
933    }
934
935    #[test]
936    fn test_event_mutator_iter_last() {
937        use bevy_ecs::prelude::*;
938
939        let mut world = World::new();
940        world.init_resource::<Messages<TestEvent>>();
941
942        let mut mutator = IntoSystem::into_system(
943            |mut events: MessageMutator<TestEvent>| -> Option<TestEvent> {
944                events.read().last().copied()
945            },
946        );
947        mutator.initialize(&mut world);
948
949        let last = mutator.run((), &mut world).unwrap();
950        assert!(last.is_none(), "EventMutator should be empty");
951
952        world.write_message(TestEvent { i: 0 });
953        let last = mutator.run((), &mut world).unwrap();
954        assert_eq!(last, Some(TestEvent { i: 0 }));
955
956        world.write_message(TestEvent { i: 1 });
957        world.write_message(TestEvent { i: 2 });
958        world.write_message(TestEvent { i: 3 });
959        let last = mutator.run((), &mut world).unwrap();
960        assert_eq!(last, Some(TestEvent { i: 3 }));
961
962        let last = mutator.run((), &mut world).unwrap();
963        assert!(last.is_none(), "EventMutator should be empty");
964    }
965
966    #[test]
967    fn test_event_reader_iter_nth() {
968        use bevy_ecs::prelude::*;
969
970        let mut world = World::new();
971        world.init_resource::<Messages<TestEvent>>();
972
973        world.write_message(TestEvent { i: 0 });
974        world.write_message(TestEvent { i: 1 });
975        world.write_message(TestEvent { i: 2 });
976        world.write_message(TestEvent { i: 3 });
977        world.write_message(TestEvent { i: 4 });
978
979        let mut schedule = Schedule::default();
980        schedule.add_systems(|mut events: MessageReader<TestEvent>| {
981            let mut iter = events.read();
982
983            assert_eq!(iter.next(), Some(&TestEvent { i: 0 }));
984            assert_eq!(iter.nth(2), Some(&TestEvent { i: 3 }));
985            assert_eq!(iter.nth(1), None);
986
987            assert!(events.is_empty());
988        });
989        schedule.run(&mut world);
990    }
991
992    #[test]
993    fn test_event_mutator_iter_nth() {
994        use bevy_ecs::prelude::*;
995
996        let mut world = World::new();
997        world.init_resource::<Messages<TestEvent>>();
998
999        world.write_message(TestEvent { i: 0 });
1000        world.write_message(TestEvent { i: 1 });
1001        world.write_message(TestEvent { i: 2 });
1002        world.write_message(TestEvent { i: 3 });
1003        world.write_message(TestEvent { i: 4 });
1004
1005        let mut schedule = Schedule::default();
1006        schedule.add_systems(|mut events: MessageReader<TestEvent>| {
1007            let mut iter = events.read();
1008
1009            assert_eq!(iter.next(), Some(&TestEvent { i: 0 }));
1010            assert_eq!(iter.nth(2), Some(&TestEvent { i: 3 }));
1011            assert_eq!(iter.nth(1), None);
1012
1013            assert!(events.is_empty());
1014        });
1015        schedule.run(&mut world);
1016    }
1017
1018    #[test]
1019    fn test_derive_entity_event() {
1020        use bevy_ecs::prelude::*;
1021
1022        struct Entitoid(Entity);
1023
1024        impl ContainsEntity for Entitoid {
1025            fn entity(&self) -> Entity {
1026                self.0
1027            }
1028        }
1029
1030        struct MutableEntitoid(Entity);
1031
1032        impl ContainsEntity for MutableEntitoid {
1033            fn entity(&self) -> Entity {
1034                self.0
1035            }
1036        }
1037
1038        impl From<Entity> for MutableEntitoid {
1039            fn from(value: Entity) -> Self {
1040                Self(value)
1041            }
1042        }
1043
1044        #[derive(EntityEvent)]
1045        struct A(Entity);
1046
1047        #[derive(EntityEvent)]
1048        #[entity_event(propagate)]
1049        struct AP(Entity);
1050
1051        #[derive(EntityEvent)]
1052        struct B {
1053            entity: Entity,
1054        }
1055
1056        #[derive(EntityEvent)]
1057        #[entity_event(propagate)]
1058        struct BP {
1059            entity: Entity,
1060        }
1061
1062        #[derive(EntityEvent)]
1063        struct C {
1064            #[event_target]
1065            target: Entity,
1066        }
1067
1068        #[derive(EntityEvent)]
1069        #[entity_event(propagate)]
1070        struct CP {
1071            #[event_target]
1072            target: Entity,
1073        }
1074
1075        #[derive(EntityEvent)]
1076        struct D(Entitoid);
1077
1078        // SHOULD NOT COMPILE:
1079        // #[derive(EntityEvent)]
1080        // #[entity_event(propagate)]
1081        // struct DP(Entitoid);
1082
1083        #[derive(EntityEvent)]
1084        struct E {
1085            entity: Entitoid,
1086        }
1087
1088        // SHOULD NOT COMPILE:
1089        // #[derive(EntityEvent)]
1090        // #[entity_event(propagate)]
1091        // struct EP {
1092        //     entity: Entitoid,
1093        // }
1094
1095        #[derive(EntityEvent)]
1096        struct F {
1097            #[event_target]
1098            target: Entitoid,
1099        }
1100
1101        // SHOULD NOT COMPILE:
1102        // #[derive(EntityEvent)]
1103        // #[entity_event(propagate)]
1104        // struct FP {
1105        //     #[event_target]
1106        //     target: Entitoid,
1107        // }
1108
1109        #[derive(EntityEvent)]
1110        #[entity_event(propagate)]
1111        struct G(MutableEntitoid);
1112
1113        impl From<Entity> for G {
1114            fn from(value: Entity) -> Self {
1115                Self(value.into())
1116            }
1117        }
1118
1119        let mut world = World::new();
1120        let entity = world.spawn_empty().id();
1121
1122        world.entity_mut(entity).trigger(A);
1123        world.entity_mut(entity).trigger(AP);
1124        world.trigger(B { entity });
1125        world.trigger(BP { entity });
1126        world.trigger(C { target: entity });
1127        world.trigger(CP { target: entity });
1128        world.trigger(D(Entitoid(entity)));
1129        world.trigger(E {
1130            entity: Entitoid(entity),
1131        });
1132        world.trigger(F {
1133            target: Entitoid(entity),
1134        });
1135        world.trigger(G(MutableEntitoid(entity)));
1136        world.entity_mut(entity).trigger(G::from);
1137
1138        // No asserts; test just needs to compile
1139    }
1140}
bevy_ecs/event/mod.rs

bevy_ecs/event/
mod.rs
