forked from bevyengine/bevy
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Created an EventMutator for when you want to mutate an event before r…
…eading (bevyengine#13818) # Objective - Often in games you will want to create chains of systems that modify some event. For example, a chain of damage systems that handle a DamageEvent and modify the underlying value before the health system finally consumes the event. Right now this requires either: * Using a component added to the entity * Consuming and refiring events Neither is ideal when really all we want to do is read the events value, modify it, and write it back. ## Solution - Create an EventMutator class similar to EventReader but with ResMut<T> and iterators that return &mut so that events can be mutated. ## Testing - I replicated all the existing tests for EventReader to make sure behavior was the same (I believe) and added a number of tests specific to testing that 1) events can actually be mutated, and that 2) EventReader sees changes from EventMutator for events it hasn't already seen. ## Migration Guide Users currently using `ManualEventReader` should use `EventCursor` instead. `ManualEventReader` will be removed in Bevy 0.16. Additionally, `Events::get_reader` has been replaced by `Events::get_cursor`. Users currently directly accessing the `Events` resource for mutation should move to `EventMutator` if possible. --------- Co-authored-by: poopy <[email protected]> Co-authored-by: Alice Cecile <[email protected]>
- Loading branch information
3 people
authored
Jul 8, 2024
1 parent
8df10d2
commit ec1aa48
Showing
17 changed files
with
1,099 additions
and
393 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,150 @@ | ||
| use crate as bevy_ecs; | ||
| use bevy_ecs::event::{ | ||
| Event, EventIterator, EventIteratorWithId, EventMutIterator, EventMutIteratorWithId, Events, | ||
| }; | ||
| #[cfg(feature = "multi_threaded")] | ||
| use bevy_ecs::event::{EventMutParIter, EventParIter}; | ||
| use std::marker::PhantomData; | ||
|
|
||
| // Deprecated in favor of `EventCursor`, there is no nice way to deprecate this | ||
| // because generic constraints are not allowed in type aliases, so this will always | ||
| // 'dead code'. Hence the `#[allow(dead_code)]`. | ||
| #[deprecated( | ||
| since = "0.14.0", | ||
| note = "`ManualEventReader` has been replaced. Please use `EventCursor` instead." | ||
| )] | ||
| #[doc(alias = "EventCursor")] | ||
| #[allow(dead_code)] | ||
| pub type ManualEventReader<E> = EventCursor<E>; | ||
|
|
||
| /// Stores the state for an [`EventReader`] or [`EventMutator`]. | ||
| /// | ||
| /// Access to the [`Events<E>`] resource is required to read any incoming events. | ||
| /// | ||
| /// In almost all cases, you should just use an [`EventReader`] or [`EventMutator`], | ||
| /// which will automatically manage the state for you. | ||
| /// | ||
| /// However, this type can be useful if you need to manually track events, | ||
| /// such as when you're attempting to send and receive events of the same type in the same system. | ||
| /// | ||
| /// # Example | ||
| /// | ||
| /// ``` | ||
| /// use bevy_ecs::prelude::*; | ||
| /// use bevy_ecs::event::{Event, Events, EventCursor}; | ||
| /// | ||
| /// #[derive(Event, Clone, Debug)] | ||
| /// struct MyEvent; | ||
| /// | ||
| /// /// A system that both sends and receives events using a [`Local`] [`EventCursor`]. | ||
| /// fn send_and_receive_events( | ||
| /// // The `Local` `SystemParam` stores state inside the system itself, rather than in the world. | ||
| /// // `EventCursor<T>` is the internal state of `EventMutator<T>`, which tracks which events have been seen. | ||
| /// mut local_event_reader: Local<EventCursor<MyEvent>>, | ||
| /// // We can access the `Events` resource mutably, allowing us to both read and write its contents. | ||
| /// mut events: ResMut<Events<MyEvent>>, | ||
| /// ) { | ||
| /// // We must collect the events to resend, because we can't mutate events while we're iterating over the events. | ||
| /// let mut events_to_resend = Vec::new(); | ||
| /// | ||
| /// for event in local_event_reader.read(&mut events) { | ||
| /// events_to_resend.push(event.clone()); | ||
| /// } | ||
| /// | ||
| /// for event in events_to_resend { | ||
| /// events.send(MyEvent); | ||
| /// } | ||
| /// } | ||
| /// | ||
| /// # bevy_ecs::system::assert_is_system(send_and_receive_events); | ||
| /// ``` | ||
| #[derive(Debug)] | ||
| pub struct EventCursor<E: Event> { | ||
| pub(super) last_event_count: usize, | ||
| pub(super) _marker: PhantomData<E>, | ||
| } | ||
|
|
||
| impl<E: Event> Default for EventCursor<E> { | ||
| fn default() -> Self { | ||
| EventCursor { | ||
| last_event_count: 0, | ||
| _marker: Default::default(), | ||
| } | ||
| } | ||
| } | ||
|
|
||
| impl<E: Event> Clone for EventCursor<E> { | ||
| fn clone(&self) -> Self { | ||
| EventCursor { | ||
| last_event_count: self.last_event_count, | ||
| _marker: PhantomData, | ||
| } | ||
| } | ||
| } | ||
|
|
||
| #[allow(clippy::len_without_is_empty)] // Check fails since the is_empty implementation has a signature other than `(&self) -> bool` | ||
| impl<E: Event> EventCursor<E> { | ||
| /// See [`EventReader::read`] | ||
| pub fn read<'a>(&'a mut self, events: &'a Events<E>) -> EventIterator<'a, E> { | ||
| self.read_with_id(events).without_id() | ||
| } | ||
|
|
||
| /// See [`EventMutator::read`] | ||
| pub fn read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutIterator<'a, E> { | ||
| self.read_mut_with_id(events).without_id() | ||
| } | ||
|
|
||
| /// See [`EventReader::read_with_id`] | ||
| pub fn read_with_id<'a>(&'a mut self, events: &'a Events<E>) -> EventIteratorWithId<'a, E> { | ||
| EventIteratorWithId::new(self, events) | ||
| } | ||
|
|
||
| /// See [`EventMutator::read_with_id`] | ||
| pub fn read_mut_with_id<'a>( | ||
| &'a mut self, | ||
| events: &'a mut Events<E>, | ||
| ) -> EventMutIteratorWithId<'a, E> { | ||
| EventMutIteratorWithId::new(self, events) | ||
| } | ||
|
|
||
| /// See [`EventReader::par_read`] | ||
| #[cfg(feature = "multi_threaded")] | ||
| pub fn par_read<'a>(&'a mut self, events: &'a Events<E>) -> EventParIter<'a, E> { | ||
| EventParIter::new(self, events) | ||
| } | ||
|
|
||
| /// See [`EventMutator::par_read`] | ||
| #[cfg(feature = "multi_threaded")] | ||
| pub fn par_read_mut<'a>(&'a mut self, events: &'a mut Events<E>) -> EventMutParIter<'a, E> { | ||
| EventMutParIter::new(self, events) | ||
| } | ||
|
|
||
| /// See [`EventReader::len`] | ||
| pub fn len(&self, events: &Events<E>) -> usize { | ||
| // The number of events in this reader is the difference between the most recent event | ||
| // and the last event seen by it. This will be at most the number of events contained | ||
| // with the events (any others have already been dropped) | ||
| // TODO: Warn when there are dropped events, or return e.g. a `Result<usize, (usize, usize)>` | ||
| events | ||
| .event_count | ||
| .saturating_sub(self.last_event_count) | ||
| .min(events.len()) | ||
| } | ||
|
|
||
| /// Amount of events we missed. | ||
| pub fn missed_events(&self, events: &Events<E>) -> usize { | ||
| events | ||
| .oldest_event_count() | ||
| .saturating_sub(self.last_event_count) | ||
| } | ||
|
|
||
| /// See [`EventReader::is_empty()`] | ||
| pub fn is_empty(&self, events: &Events<E>) -> bool { | ||
| self.len(events) == 0 | ||
| } | ||
|
|
||
| /// See [`EventReader::clear()`] | ||
| pub fn clear(&mut self, events: &Events<E>) { | ||
| self.last_event_count = events.event_count; | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.