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/// ## Trigger Behavior
139///
140/// When derived, [`EntityEvent`] defaults to setting [`Event::Trigger`] to [`EntityTrigger`], which will run all normal "untargeted"
141/// observers added via [`World::add_observer`], just like a default [`Event`] would (see the example above).
142///
143/// However it will _also_ run all observers that watch _specific_ entities, which enables you to assign entity-specific logic:
144///
145/// ```
146/// # use bevy_ecs::prelude::*;
147/// # #[derive(Component, Debug)]
148/// # struct Name(String);
149/// # let mut world = World::default();
150/// # let e1 = world.spawn_empty().id();
151/// # let e2 = world.spawn_empty().id();
152/// # #[derive(EntityEvent)]
153/// # struct Explode {
154/// #    entity: Entity,
155/// # }
156/// world.entity_mut(e1).observe(|event: On<Explode>, mut commands: Commands| {
157///     println!("Boom!");
158///     commands.entity(event.entity).despawn();
159/// });
160///
161/// world.entity_mut(e2).observe(|event: On<Explode>, mut commands: Commands| {
162///     println!("The explosion fizzles! This entity is immune!");
163/// });
164/// ```
165///
166/// ## [`EntityEvent`] Propagation
167///
168/// When deriving [`EntityEvent`], you can enable "event propagation" (also known as "event bubbling") by
169/// specifying the `#[entity_event(propagate)]` attribute:
170///
171/// ```
172/// # use bevy_ecs::prelude::*;
173/// #[derive(EntityEvent)]
174/// #[entity_event(propagate)]
175/// struct Click {
176///     entity: Entity,
177/// }
178/// ```
179///
180/// This will default to using the [`ChildOf`](crate::hierarchy::ChildOf) component to propagate the [`Event`] "up"
181/// the hierarchy (from child to parent).
182///
183/// You can also specify your own [`Traversal`](crate::traversal::Traversal) implementation. A common pattern is to use
184/// [`Relationship`](crate::relationship::Relationship) components, which will follow the relationships to their root
185/// (just be sure to avoid cycles ... these aren't detected for performance reasons):
186///
187/// ```
188/// # use bevy_ecs::prelude::*;
189/// #[derive(Component)]
190/// #[relationship(relationship_target = ClickableBy)]
191/// struct Clickable(Entity);
192///
193/// #[derive(Component)]
194/// #[relationship_target(relationship = Clickable)]
195/// struct ClickableBy(Vec<Entity>);
196///
197/// #[derive(EntityEvent)]
198/// #[entity_event(propagate = &'static Clickable)]
199/// struct Click {
200///     entity: Entity,
201/// }
202/// ```
203///
204/// By default, propagation requires observers to opt-in:
205///
206/// ```
207/// # use bevy_ecs::prelude::*;
208/// #[derive(EntityEvent)]
209/// #[entity_event(propagate)]
210/// struct Click {
211///     entity: Entity,
212/// }
213///
214/// # let mut world = World::default();
215/// world.add_observer(|mut click: On<Click>| {
216///   // this will propagate the event up to the parent, using `ChildOf`
217///   click.propagate(true);
218/// });
219/// ```
220///
221/// But you can enable auto propagation using the `#[entity_event(auto_propagate)]` attribute:
222/// ```
223/// # use bevy_ecs::prelude::*;
224/// #[derive(EntityEvent)]
225/// #[entity_event(propagate, auto_propagate)]
226/// struct Click {
227///     entity: Entity,
228/// }
229/// ```
230///
231/// You can also _stop_ propagation like this:
232/// ```
233/// # use bevy_ecs::prelude::*;
234/// # #[derive(EntityEvent)]
235/// # #[entity_event(propagate)]
236/// # struct Click {
237/// #    entity: Entity,
238/// # }
239/// # fn is_finished_propagating() -> bool { true }
240/// # let mut world = World::default();
241/// world.add_observer(|mut click: On<Click>| {
242///   if is_finished_propagating() {
243///     click.propagate(false);
244///   }
245/// });
246/// ```
247///
248/// ## Naming and Usage Conventions
249///
250/// In most cases, it is recommended to use a named struct field for the "event target" entity, and to use
251/// a name that is descriptive as possible, as this makes events easier to understand and read.
252///
253/// For events with only one [`Entity`] field, `entity` is often a reasonable name. But if there are multiple
254/// [`Entity`] fields, it is often a good idea to use a more descriptive name.
255///
256/// It is also generally recommended to _consume_ "event target" entities directly via their named field, as this
257/// can make the context clearer, allows for more specific documentation hints in IDEs, and it generally reads better.
258///
259/// ## Manually spawning [`EntityEvent`] observers
260///
261/// The examples above that call [`EntityWorldMut::observe`] to add entity-specific observer logic are
262/// just shorthand for spawning an [`Observer`] directly and manually watching the entity:
263///
264/// ```
265/// # use bevy_ecs::prelude::*;
266/// # let mut world = World::default();
267/// # let entity = world.spawn_empty().id();
268/// # #[derive(EntityEvent)]
269/// # struct Explode(Entity);
270/// let mut observer = Observer::new(|event: On<Explode>| {});
271/// observer.watch_entity(entity);
272/// world.spawn(observer);
273/// ```
274///
275/// Note that the [`Observer`] component is not added to the entity it is observing. Observers should always be their own entities, as there
276/// can be multiple observers of the same entity!
277///
278/// You can call [`Observer::watch_entity`] more than once or [`Observer::watch_entities`] to watch multiple entities with the same [`Observer`].
279///
280/// [`EntityWorldMut::observe`]: crate::world::EntityWorldMut::observe
281/// [`Observer`]: crate::observer::Observer
282/// [`Observer::watch_entity`]: crate::observer::Observer::watch_entity
283/// [`Observer::watch_entities`]: crate::observer::Observer::watch_entities
284pub trait EntityEvent: Event {
285    /// The [`Entity`] "target" of this [`EntityEvent`]. When triggered, this will run observers that watch for this specific entity.
286    fn event_target(&self) -> Entity;
287    /// Returns a mutable reference to the [`Entity`] "target" of this [`EntityEvent`]. When triggered, this will run observers that watch for this specific entity.
288    ///
289    /// Note: In general, this should not be mutated from within an [`Observer`](crate::observer::Observer), as this will not "retarget"
290    /// the event in any of Bevy's built-in [`Trigger`] implementations.
291    fn event_target_mut(&mut self) -> &mut Entity;
292}
293
294impl World {
295    /// Generates the [`EventKey`] for this event type.
296    ///
297    /// If this type has already been registered,
298    /// this will return the existing [`EventKey`].
299    ///
300    /// This is used by various dynamically typed observer APIs,
301    /// such as [`DeferredWorld::trigger_raw`](crate::world::DeferredWorld::trigger_raw).
302    pub fn register_event_key<E: Event>(&mut self) -> EventKey {
303        EventKey(self.register_component::<EventWrapperComponent<E>>())
304    }
305
306    /// Fetches the [`EventKey`] for this event type,
307    /// if it has already been generated.
308    ///
309    /// This is used by various dynamically typed observer APIs,
310    /// such as [`DeferredWorld::trigger_raw`](crate::world::DeferredWorld::trigger_raw).
311    pub fn event_key<E: Event>(&self) -> Option<EventKey> {
312        self.component_id::<EventWrapperComponent<E>>()
313            .map(EventKey)
314    }
315}
316
317/// An internal type that implements [`Component`] for a given [`Event`] type.
318///
319/// This exists so we can easily get access to a unique [`ComponentId`] for each [`Event`] type,
320/// without requiring that [`Event`] types implement [`Component`] directly.
321/// [`ComponentId`] is used internally as a unique identifier for events because they are:
322///
323/// - Unique to each event type.
324/// - Can be quickly generated and looked up.
325/// - Are compatible with dynamic event types, which aren't backed by a Rust type.
326///
327/// This type is an implementation detail and should never be made public.
328// TODO: refactor events to store their metadata on distinct entities, rather than using `ComponentId`
329#[derive(Component)]
330struct EventWrapperComponent<E: Event>(PhantomData<E>);
331
332/// A unique identifier for an [`Event`], used by [observers].
333///
334/// You can look up the key for your event by calling the [`World::event_key`] method.
335///
336/// [observers]: crate::observer
337#[derive(Debug, Copy, Clone, Hash, Ord, PartialOrd, Eq, PartialEq)]
338pub struct EventKey(pub(crate) ComponentId);
339
340/// This is deprecated. See [`MessageCursor`](crate::message::MessageCursor)
341#[deprecated(since = "0.17.0", note = "Renamed to `MessageCursor`.")]
342pub type EventCursor<E> = crate::message::MessageCursor<E>;
343
344/// This is deprecated. See [`MessageMutator`](crate::message::MessageMutator)
345#[deprecated(since = "0.17.0", note = "Renamed to `MessageMutator`.")]
346pub type EventMutator<'w, 's, E> = crate::message::MessageMutator<'w, 's, E>;
347
348/// This is deprecated. See [`MessageReader`](crate::message::MessageReader)
349#[deprecated(since = "0.17.0", note = "Renamed to `MessageReader`.")]
350pub type EventReader<'w, 's, E> = crate::message::MessageReader<'w, 's, E>;
351
352/// This is deprecated. See [`MessageWriter`](crate::message::MessageWriter)
353#[deprecated(since = "0.17.0", note = "Renamed to `MessageWriter`.")]
354pub type EventWriter<'w, E> = crate::message::MessageWriter<'w, E>;
355
356/// This is deprecated. See [`Messages`](crate::message::Messages)
357#[deprecated(since = "0.17.0", note = "Renamed to `Messages`.")]
358pub type Events<E> = crate::message::Messages<E>;
359
360/// This is deprecated. See [`MessageIterator`](crate::message::MessageIterator)
361#[deprecated(since = "0.17.0", note = "Renamed to `MessageIterator`.")]
362pub type EventIterator<'a, E> = crate::message::MessageIterator<'a, E>;
363
364/// This is deprecated. See [`MessageMutIterator`](crate::message::MessageMutIterator)
365#[deprecated(since = "0.17.0", note = "Renamed to `MessageIterator`.")]
366pub type EventMutIterator<'a, E> = crate::message::MessageMutIterator<'a, E>;
367
368#[cfg(test)]
369mod tests {
370    use alloc::{vec, vec::Vec};
371    use bevy_ecs::{message::*, system::assert_is_read_only_system};
372    use bevy_ecs_macros::Message;
373
374    #[derive(Message, Copy, Clone, PartialEq, Eq, Debug)]
375    struct TestEvent {
376        i: usize,
377    }
378
379    #[derive(Message, Clone, PartialEq, Debug, Default)]
380    struct EmptyTestEvent;
381
382    fn get_events<E: Message + Clone>(
383        events: &Messages<E>,
384        cursor: &mut MessageCursor<E>,
385    ) -> Vec<E> {
386        cursor.read(events).cloned().collect::<Vec<E>>()
387    }
388
389    #[test]
390    fn test_events() {
391        let mut events = Messages::<TestEvent>::default();
392        let event_0 = TestEvent { i: 0 };
393        let event_1 = TestEvent { i: 1 };
394        let event_2 = TestEvent { i: 2 };
395
396        // this reader will miss event_0 and event_1 because it wont read them over the course of
397        // two updates
398        let mut reader_missed: MessageCursor<TestEvent> = events.get_cursor();
399
400        let mut reader_a: MessageCursor<TestEvent> = events.get_cursor();
401
402        events.write(event_0);
403
404        assert_eq!(
405            get_events(&events, &mut reader_a),
406            vec![event_0],
407            "reader_a created before event receives event"
408        );
409        assert_eq!(
410            get_events(&events, &mut reader_a),
411            vec![],
412            "second iteration of reader_a created before event results in zero events"
413        );
414
415        let mut reader_b: MessageCursor<TestEvent> = events.get_cursor();
416
417        assert_eq!(
418            get_events(&events, &mut reader_b),
419            vec![event_0],
420            "reader_b created after event receives event"
421        );
422        assert_eq!(
423            get_events(&events, &mut reader_b),
424            vec![],
425            "second iteration of reader_b created after event results in zero events"
426        );
427
428        events.write(event_1);
429
430        let mut reader_c = events.get_cursor();
431
432        assert_eq!(
433            get_events(&events, &mut reader_c),
434            vec![event_0, event_1],
435            "reader_c created after two events receives both events"
436        );
437        assert_eq!(
438            get_events(&events, &mut reader_c),
439            vec![],
440            "second iteration of reader_c created after two event results in zero events"
441        );
442
443        assert_eq!(
444            get_events(&events, &mut reader_a),
445            vec![event_1],
446            "reader_a receives next unread event"
447        );
448
449        events.update();
450
451        let mut reader_d = events.get_cursor();
452
453        events.write(event_2);
454
455        assert_eq!(
456            get_events(&events, &mut reader_a),
457            vec![event_2],
458            "reader_a receives event created after update"
459        );
460        assert_eq!(
461            get_events(&events, &mut reader_b),
462            vec![event_1, event_2],
463            "reader_b receives events created before and after update"
464        );
465        assert_eq!(
466            get_events(&events, &mut reader_d),
467            vec![event_0, event_1, event_2],
468            "reader_d receives all events created before and after update"
469        );
470
471        events.update();
472
473        assert_eq!(
474            get_events(&events, &mut reader_missed),
475            vec![event_2],
476            "reader_missed missed events unread after two update() calls"
477        );
478    }
479
480    // Events Collection
481    fn events_clear_and_read_impl(clear_func: impl FnOnce(&mut Messages<TestEvent>)) {
482        let mut events = Messages::<TestEvent>::default();
483        let mut reader = events.get_cursor();
484
485        assert!(reader.read(&events).next().is_none());
486
487        events.write(TestEvent { i: 0 });
488        assert_eq!(*reader.read(&events).next().unwrap(), TestEvent { i: 0 });
489        assert_eq!(reader.read(&events).next(), None);
490
491        events.write(TestEvent { i: 1 });
492        clear_func(&mut events);
493        assert!(reader.read(&events).next().is_none());
494
495        events.write(TestEvent { i: 2 });
496        events.update();
497        events.write(TestEvent { i: 3 });
498
499        assert!(reader
500            .read(&events)
501            .eq([TestEvent { i: 2 }, TestEvent { i: 3 }].iter()));
502    }
503
504    #[test]
505    fn test_events_clear_and_read() {
506        events_clear_and_read_impl(Messages::clear);
507    }
508
509    #[test]
510    fn test_events_drain_and_read() {
511        events_clear_and_read_impl(|events| {
512            assert!(events
513                .drain()
514                .eq(vec![TestEvent { i: 0 }, TestEvent { i: 1 }].into_iter()));
515        });
516    }
517
518    #[test]
519    fn test_events_write_default() {
520        let mut events = Messages::<EmptyTestEvent>::default();
521        events.write_default();
522
523        let mut reader = events.get_cursor();
524        assert_eq!(get_events(&events, &mut reader), vec![EmptyTestEvent]);
525    }
526
527    #[test]
528    fn test_write_events_ids() {
529        let mut events = Messages::<TestEvent>::default();
530        let event_0 = TestEvent { i: 0 };
531        let event_1 = TestEvent { i: 1 };
532        let event_2 = TestEvent { i: 2 };
533
534        let event_0_id = events.write(event_0);
535
536        assert_eq!(
537            events.get_message(event_0_id.id),
538            Some((&event_0, event_0_id)),
539            "Getting a sent event by ID should return the original event"
540        );
541
542        let mut event_ids = events.write_batch([event_1, event_2]);
543
544        let event_id = event_ids.next().expect("Event 1 must have been sent");
545
546        assert_eq!(
547            events.get_message(event_id.id),
548            Some((&event_1, event_id)),
549            "Getting a sent event by ID should return the original event"
550        );
551
552        let event_id = event_ids.next().expect("Event 2 must have been sent");
553
554        assert_eq!(
555            events.get_message(event_id.id),
556            Some((&event_2, event_id)),
557            "Getting a sent event by ID should return the original event"
558        );
559
560        assert!(
561            event_ids.next().is_none(),
562            "Only sent two events; got more than two IDs"
563        );
564    }
565
566    #[test]
567    fn test_event_registry_can_add_and_remove_events_to_world() {
568        use bevy_ecs::prelude::*;
569
570        let mut world = World::new();
571        MessageRegistry::register_message::<TestEvent>(&mut world);
572
573        let has_events = world.get_resource::<Messages<TestEvent>>().is_some();
574        assert!(has_events, "Should have the events resource");
575
576        MessageRegistry::deregister_messages::<TestEvent>(&mut world);
577
578        let has_events = world.get_resource::<Messages<TestEvent>>().is_some();
579        assert!(!has_events, "Should not have the events resource");
580    }
581
582    #[test]
583    fn test_events_update_drain() {
584        let mut events = Messages::<TestEvent>::default();
585        let mut reader = events.get_cursor();
586
587        events.write(TestEvent { i: 0 });
588        events.write(TestEvent { i: 1 });
589        assert_eq!(reader.read(&events).count(), 2);
590
591        let mut old_events = Vec::from_iter(events.update_drain());
592        assert!(old_events.is_empty());
593
594        events.write(TestEvent { i: 2 });
595        assert_eq!(reader.read(&events).count(), 1);
596
597        old_events.extend(events.update_drain());
598        assert_eq!(old_events.len(), 2);
599
600        old_events.extend(events.update_drain());
601        assert_eq!(
602            old_events,
603            &[TestEvent { i: 0 }, TestEvent { i: 1 }, TestEvent { i: 2 }]
604        );
605    }
606
607    #[test]
608    fn test_events_empty() {
609        let mut events = Messages::<TestEvent>::default();
610        assert!(events.is_empty());
611
612        events.write(TestEvent { i: 0 });
613        assert!(!events.is_empty());
614
615        events.update();
616        assert!(!events.is_empty());
617
618        // events are only empty after the second call to update
619        // due to double buffering.
620        events.update();
621        assert!(events.is_empty());
622    }
623
624    #[test]
625    fn test_events_extend_impl() {
626        let mut events = Messages::<TestEvent>::default();
627        let mut reader = events.get_cursor();
628
629        events.extend(vec![TestEvent { i: 0 }, TestEvent { i: 1 }]);
630        assert!(reader
631            .read(&events)
632            .eq([TestEvent { i: 0 }, TestEvent { i: 1 }].iter()));
633    }
634
635    // Cursor
636    #[test]
637    fn test_event_cursor_read() {
638        let mut events = Messages::<TestEvent>::default();
639        let mut cursor = events.get_cursor();
640        assert!(cursor.read(&events).next().is_none());
641
642        events.write(TestEvent { i: 0 });
643        let sent_event = cursor.read(&events).next().unwrap();
644        assert_eq!(sent_event, &TestEvent { i: 0 });
645        assert!(cursor.read(&events).next().is_none());
646
647        events.write(TestEvent { i: 2 });
648        let sent_event = cursor.read(&events).next().unwrap();
649        assert_eq!(sent_event, &TestEvent { i: 2 });
650        assert!(cursor.read(&events).next().is_none());
651
652        events.clear();
653        assert!(cursor.read(&events).next().is_none());
654    }
655
656    #[test]
657    fn test_event_cursor_read_mut() {
658        let mut events = Messages::<TestEvent>::default();
659        let mut write_cursor = events.get_cursor();
660        let mut read_cursor = events.get_cursor();
661        assert!(write_cursor.read_mut(&mut events).next().is_none());
662        assert!(read_cursor.read(&events).next().is_none());
663
664        events.write(TestEvent { i: 0 });
665        let sent_event = write_cursor.read_mut(&mut events).next().unwrap();
666        assert_eq!(sent_event, &mut TestEvent { i: 0 });
667        *sent_event = TestEvent { i: 1 }; // Mutate whole event
668        assert_eq!(
669            read_cursor.read(&events).next().unwrap(),
670            &TestEvent { i: 1 }
671        );
672        assert!(read_cursor.read(&events).next().is_none());
673
674        events.write(TestEvent { i: 2 });
675        let sent_event = write_cursor.read_mut(&mut events).next().unwrap();
676        assert_eq!(sent_event, &mut TestEvent { i: 2 });
677        sent_event.i = 3; // Mutate sub value
678        assert_eq!(
679            read_cursor.read(&events).next().unwrap(),
680            &TestEvent { i: 3 }
681        );
682        assert!(read_cursor.read(&events).next().is_none());
683
684        events.clear();
685        assert!(write_cursor.read(&events).next().is_none());
686        assert!(read_cursor.read(&events).next().is_none());
687    }
688
689    #[test]
690    fn test_event_cursor_clear() {
691        let mut events = Messages::<TestEvent>::default();
692        let mut reader = events.get_cursor();
693
694        events.write(TestEvent { i: 0 });
695        assert_eq!(reader.len(&events), 1);
696        reader.clear(&events);
697        assert_eq!(reader.len(&events), 0);
698    }
699
700    #[test]
701    fn test_event_cursor_len_update() {
702        let mut events = Messages::<TestEvent>::default();
703        events.write(TestEvent { i: 0 });
704        events.write(TestEvent { i: 0 });
705        let reader = events.get_cursor();
706        assert_eq!(reader.len(&events), 2);
707        events.update();
708        events.write(TestEvent { i: 0 });
709        assert_eq!(reader.len(&events), 3);
710        events.update();
711        assert_eq!(reader.len(&events), 1);
712        events.update();
713        assert!(reader.is_empty(&events));
714    }
715
716    #[test]
717    fn test_event_cursor_len_current() {
718        let mut events = Messages::<TestEvent>::default();
719        events.write(TestEvent { i: 0 });
720        let reader = events.get_cursor_current();
721        assert!(reader.is_empty(&events));
722        events.write(TestEvent { i: 0 });
723        assert_eq!(reader.len(&events), 1);
724        assert!(!reader.is_empty(&events));
725    }
726
727    #[test]
728    fn test_event_cursor_iter_len_updated() {
729        let mut events = Messages::<TestEvent>::default();
730        events.write(TestEvent { i: 0 });
731        events.write(TestEvent { i: 1 });
732        events.write(TestEvent { i: 2 });
733        let mut reader = events.get_cursor();
734        let mut iter = reader.read(&events);
735        assert_eq!(iter.len(), 3);
736        iter.next();
737        assert_eq!(iter.len(), 2);
738        iter.next();
739        assert_eq!(iter.len(), 1);
740        iter.next();
741        assert_eq!(iter.len(), 0);
742    }
743
744    #[test]
745    fn test_event_cursor_len_empty() {
746        let events = Messages::<TestEvent>::default();
747        assert_eq!(events.get_cursor().len(&events), 0);
748        assert!(events.get_cursor().is_empty(&events));
749    }
750
751    #[test]
752    fn test_event_cursor_len_filled() {
753        let mut events = Messages::<TestEvent>::default();
754        events.write(TestEvent { i: 0 });
755        assert_eq!(events.get_cursor().len(&events), 1);
756        assert!(!events.get_cursor().is_empty(&events));
757    }
758
759    #[cfg(feature = "multi_threaded")]
760    #[test]
761    fn test_event_cursor_par_read() {
762        use crate::prelude::*;
763        use core::sync::atomic::{AtomicUsize, Ordering};
764
765        #[derive(Resource)]
766        struct Counter(AtomicUsize);
767
768        let mut world = World::new();
769        world.init_resource::<Messages<TestEvent>>();
770        for _ in 0..100 {
771            world.write_message(TestEvent { i: 1 });
772        }
773
774        let mut schedule = Schedule::default();
775
776        schedule.add_systems(
777            |mut cursor: Local<MessageCursor<TestEvent>>,
778             events: Res<Messages<TestEvent>>,
779             counter: ResMut<Counter>| {
780                cursor.par_read(&events).for_each(|event| {
781                    counter.0.fetch_add(event.i, Ordering::Relaxed);
782                });
783            },
784        );
785
786        world.insert_resource(Counter(AtomicUsize::new(0)));
787        schedule.run(&mut world);
788        let counter = world.remove_resource::<Counter>().unwrap();
789        assert_eq!(counter.0.into_inner(), 100);
790
791        world.insert_resource(Counter(AtomicUsize::new(0)));
792        schedule.run(&mut world);
793        let counter = world.remove_resource::<Counter>().unwrap();
794        assert_eq!(
795            counter.0.into_inner(),
796            0,
797            "par_read should have consumed events but didn't"
798        );
799    }
800
801    #[cfg(feature = "multi_threaded")]
802    #[test]
803    fn test_event_cursor_par_read_mut() {
804        use crate::prelude::*;
805        use core::sync::atomic::{AtomicUsize, Ordering};
806
807        #[derive(Resource)]
808        struct Counter(AtomicUsize);
809
810        let mut world = World::new();
811        world.init_resource::<Messages<TestEvent>>();
812        for _ in 0..100 {
813            world.write_message(TestEvent { i: 1 });
814        }
815        let mut schedule = Schedule::default();
816        schedule.add_systems(
817            |mut cursor: Local<MessageCursor<TestEvent>>,
818             mut events: ResMut<Messages<TestEvent>>,
819             counter: ResMut<Counter>| {
820                cursor.par_read_mut(&mut events).for_each(|event| {
821                    event.i += 1;
822                    counter.0.fetch_add(event.i, Ordering::Relaxed);
823                });
824            },
825        );
826        world.insert_resource(Counter(AtomicUsize::new(0)));
827        schedule.run(&mut world);
828        let counter = world.remove_resource::<Counter>().unwrap();
829        assert_eq!(counter.0.into_inner(), 200, "Initial run failed");
830
831        world.insert_resource(Counter(AtomicUsize::new(0)));
832        schedule.run(&mut world);
833        let counter = world.remove_resource::<Counter>().unwrap();
834        assert_eq!(
835            counter.0.into_inner(),
836            0,
837            "par_read_mut should have consumed events but didn't"
838        );
839    }
840
841    // Reader & Mutator
842    #[test]
843    fn ensure_reader_readonly() {
844        fn reader_system(_: MessageReader<EmptyTestEvent>) {}
845
846        assert_is_read_only_system(reader_system);
847    }
848
849    #[test]
850    fn test_event_reader_iter_last() {
851        use bevy_ecs::prelude::*;
852
853        let mut world = World::new();
854        world.init_resource::<Messages<TestEvent>>();
855
856        let mut reader = IntoSystem::into_system(
857            |mut events: MessageReader<TestEvent>| -> Option<TestEvent> {
858                events.read().last().copied()
859            },
860        );
861        reader.initialize(&mut world);
862
863        let last = reader.run((), &mut world).unwrap();
864        assert!(last.is_none(), "MessageReader should be empty");
865
866        world.write_message(TestEvent { i: 0 });
867        let last = reader.run((), &mut world).unwrap();
868        assert_eq!(last, Some(TestEvent { i: 0 }));
869
870        world.write_message(TestEvent { i: 1 });
871        world.write_message(TestEvent { i: 2 });
872        world.write_message(TestEvent { i: 3 });
873        let last = reader.run((), &mut world).unwrap();
874        assert_eq!(last, Some(TestEvent { i: 3 }));
875
876        let last = reader.run((), &mut world).unwrap();
877        assert!(last.is_none(), "MessageReader should be empty");
878    }
879
880    #[test]
881    fn test_event_mutator_iter_last() {
882        use bevy_ecs::prelude::*;
883
884        let mut world = World::new();
885        world.init_resource::<Messages<TestEvent>>();
886
887        let mut mutator = IntoSystem::into_system(
888            |mut events: MessageMutator<TestEvent>| -> Option<TestEvent> {
889                events.read().last().copied()
890            },
891        );
892        mutator.initialize(&mut world);
893
894        let last = mutator.run((), &mut world).unwrap();
895        assert!(last.is_none(), "EventMutator should be empty");
896
897        world.write_message(TestEvent { i: 0 });
898        let last = mutator.run((), &mut world).unwrap();
899        assert_eq!(last, Some(TestEvent { i: 0 }));
900
901        world.write_message(TestEvent { i: 1 });
902        world.write_message(TestEvent { i: 2 });
903        world.write_message(TestEvent { i: 3 });
904        let last = mutator.run((), &mut world).unwrap();
905        assert_eq!(last, Some(TestEvent { i: 3 }));
906
907        let last = mutator.run((), &mut world).unwrap();
908        assert!(last.is_none(), "EventMutator should be empty");
909    }
910
911    #[test]
912    fn test_event_reader_iter_nth() {
913        use bevy_ecs::prelude::*;
914
915        let mut world = World::new();
916        world.init_resource::<Messages<TestEvent>>();
917
918        world.write_message(TestEvent { i: 0 });
919        world.write_message(TestEvent { i: 1 });
920        world.write_message(TestEvent { i: 2 });
921        world.write_message(TestEvent { i: 3 });
922        world.write_message(TestEvent { i: 4 });
923
924        let mut schedule = Schedule::default();
925        schedule.add_systems(|mut events: MessageReader<TestEvent>| {
926            let mut iter = events.read();
927
928            assert_eq!(iter.next(), Some(&TestEvent { i: 0 }));
929            assert_eq!(iter.nth(2), Some(&TestEvent { i: 3 }));
930            assert_eq!(iter.nth(1), None);
931
932            assert!(events.is_empty());
933        });
934        schedule.run(&mut world);
935    }
936
937    #[test]
938    fn test_event_mutator_iter_nth() {
939        use bevy_ecs::prelude::*;
940
941        let mut world = World::new();
942        world.init_resource::<Messages<TestEvent>>();
943
944        world.write_message(TestEvent { i: 0 });
945        world.write_message(TestEvent { i: 1 });
946        world.write_message(TestEvent { i: 2 });
947        world.write_message(TestEvent { i: 3 });
948        world.write_message(TestEvent { i: 4 });
949
950        let mut schedule = Schedule::default();
951        schedule.add_systems(|mut events: MessageReader<TestEvent>| {
952            let mut iter = events.read();
953
954            assert_eq!(iter.next(), Some(&TestEvent { i: 0 }));
955            assert_eq!(iter.nth(2), Some(&TestEvent { i: 3 }));
956            assert_eq!(iter.nth(1), None);
957
958            assert!(events.is_empty());
959        });
960        schedule.run(&mut world);
961    }
962}
bevy_ecs/event/mod.rs

bevy_ecs/event/
mod.rs
