bevy_ecs/event/
base.rs

1use crate::{component::Component, traversal::Traversal};
2#[cfg(feature = "bevy_reflect")]
3use bevy_reflect::Reflect;
4use core::{
5    cmp::Ordering,
6    fmt,
7    hash::{Hash, Hasher},
8    marker::PhantomData,
9};
10
11/// Something that "happens" and might be read / observed by app logic.
12///
13/// Events can be stored in an [`Events<E>`] resource
14/// You can conveniently access events using the [`EventReader`] and [`EventWriter`] system parameter.
15///
16/// Events can also be "triggered" on a [`World`], which will then cause any [`Observer`] of that trigger to run.
17///
18/// This trait can be derived.
19///
20/// Events implement the [`Component`] type (and they automatically do when they are derived). Events are (generally)
21/// not directly inserted as components. More often, the [`ComponentId`] is used to identify the event type within the
22/// context of the ECS.
23///
24/// Events must be thread-safe.
25///
26/// [`World`]: crate::world::World
27/// [`ComponentId`]: crate::component::ComponentId
28/// [`Observer`]: crate::observer::Observer
29/// [`Events<E>`]: super::Events
30/// [`EventReader`]: super::EventReader
31/// [`EventWriter`]: super::EventWriter
32#[diagnostic::on_unimplemented(
33    message = "`{Self}` is not an `Event`",
34    label = "invalid `Event`",
35    note = "consider annotating `{Self}` with `#[derive(Event)]`"
36)]
37pub trait Event: Component {
38    /// The component that describes which Entity to propagate this event to next, when [propagation] is enabled.
39    ///
40    /// [propagation]: crate::observer::Trigger::propagate
41    type Traversal: Traversal;
42
43    /// When true, this event will always attempt to propagate when [triggered], without requiring a call
44    /// to [`Trigger::propagate`].
45    ///
46    /// [triggered]: crate::system::Commands::trigger_targets
47    /// [`Trigger::propagate`]: crate::observer::Trigger::propagate
48    const AUTO_PROPAGATE: bool = false;
49}
50
51/// An `EventId` uniquely identifies an event stored in a specific [`World`].
52///
53/// An `EventId` can among other things be used to trace the flow of an event from the point it was
54/// sent to the point it was processed. `EventId`s increase monotonically by send order.
55///
56/// [`World`]: crate::world::World
57#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
58pub struct EventId<E: Event> {
59    /// Uniquely identifies the event associated with this ID.
60    // This value corresponds to the order in which each event was added to the world.
61    pub id: usize,
62    #[cfg_attr(feature = "bevy_reflect", reflect(ignore))]
63    pub(super) _marker: PhantomData<E>,
64}
65
66impl<E: Event> Copy for EventId<E> {}
67
68impl<E: Event> Clone for EventId<E> {
69    fn clone(&self) -> Self {
70        *self
71    }
72}
73
74impl<E: Event> fmt::Display for EventId<E> {
75    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
76        <Self as fmt::Debug>::fmt(self, f)
77    }
78}
79
80impl<E: Event> fmt::Debug for EventId<E> {
81    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
82        write!(
83            f,
84            "event<{}>#{}",
85            core::any::type_name::<E>().split("::").last().unwrap(),
86            self.id,
87        )
88    }
89}
90
91impl<E: Event> PartialEq for EventId<E> {
92    fn eq(&self, other: &Self) -> bool {
93        self.id == other.id
94    }
95}
96
97impl<E: Event> Eq for EventId<E> {}
98
99impl<E: Event> PartialOrd for EventId<E> {
100    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
101        Some(self.cmp(other))
102    }
103}
104
105impl<E: Event> Ord for EventId<E> {
106    fn cmp(&self, other: &Self) -> Ordering {
107        self.id.cmp(&other.id)
108    }
109}
110
111impl<E: Event> Hash for EventId<E> {
112    fn hash<H: Hasher>(&self, state: &mut H) {
113        Hash::hash(&self.id, state);
114    }
115}
116
117#[derive(Debug)]
118#[cfg_attr(feature = "bevy_reflect", derive(Reflect))]
119pub(crate) struct EventInstance<E: Event> {
120    pub event_id: EventId<E>,
121    pub event: E,
122}
bevy_ecs/event/base.rs

bevy_ecs/event/
base.rs
