Add event_consumer example

Author: alice-i-cecile

Cargo.toml

@@ -259,6 +259,10 @@ path = "examples/ecs/change_detection.rs"
 name = "event"
 path = "examples/ecs/event.rs"
 
+[[example]]
+name = "event_consumer"
+path = "examples/ecs/event_consumer.rs"
+
 [[example]]
 name = "fixed_timestep"
 path = "examples/ecs/fixed_timestep.rs"

crates/bevy_ecs/src/lib.rs

@@ -19,7 +19,7 @@ pub mod prelude {
     pub use crate::{
         bundle::Bundle,
         entity::Entity,
-        event::{EventReader, EventWriter},
+        event::{EventConsumer, EventReader, EventWriter},
         query::{Added, ChangeTrackers, Changed, Or, QueryState, With, WithBundle, Without},
         schedule::{
             AmbiguitySetLabel, ExclusiveSystemDescriptorCoercion, ParallelSystemDescriptorCoercion,

examples/README.md

@@ -151,6 +151,7 @@ Example | File | Description
 `ecs_guide` | [`ecs/ecs_guide.rs`](./ecs/ecs_guide.rs) | Full guide to Bevy's ECS
 `change_detection` | [`ecs/change_detection.rs`](./ecs/change_detection.rs) | Change detection on components
 `event` | [`ecs/event.rs`](./ecs/event.rs) | Illustrates event creation, activation, and reception
+`event_consumer` | [`ecs/event_consumer.rs`](./ecs/event_consumer.rs) | Shows how to consume events and avoid automatic event cleanup when skipping systems
 `fixed_timestep` | [`ecs/fixed_timestep.rs`](./ecs/fixed_timestep.rs) | Shows how to create systems that run every fixed timestep, rather than every tick
 `hierarchy` | [`ecs/hierarchy.rs`](./ecs/hierarchy.rs) | Creates a hierarchy of parents and children entities
 `parallel_query` | [`ecs/parallel_query.rs`](./ecs/parallel_query.rs) | Illustrates parallel queries with `ParallelIterator`

examples/ecs/event_consumer.rs

@@ -0,0 +1,65 @@
+use bevy::core::FixedTimestep;
+use bevy::prelude::*;
+
+/// Events are automatically cleaned up after two frames when intialized via `.add_event`.
+/// To bypass this, you can simply add the Events::<T> resource manually.
+/// This is critical when working with systems that read events but do not run every tick,
+/// such as those that operate with a FixedTimeStep run criteria.
+///
+/// When you do so though, you need to be careful to clean up these events eventually,
+/// otherwise the size of your vector of events will grow in an unbounded fashion.
+///
+/// `EventConsumer::<T>` provides a simple interface to do so, clearing all events that it reads
+/// by draining them into a new vector.
+/// You can combine it with other `EventReader`s as long as they read events before ,
+/// but only one `EventConsumer` system should be used per event type in most cases
+/// as they will compete for events.
+fn main() {
+    App::build()
+        .add_plugins(DefaultPlugins)
+        .add_event::<MyEvent>()
+        .add_system(
+            event_trigger_system
+                .system()
+                .with_run_criteria(FixedTimestep::step(1.0)),
+        )
+        .add_system(event_listener_system.system().label("listening"))
+        .add_system(
+            event_devourer_system
+                .system()
+                // Must occur after event_listener_system or some events may be missed
+                .after("listening")
+                .with_run_criteria(FixedTimestep::step(5.0)),
+        )
+        .run();
+}
+
+struct MyEvent {
+    pub message: String,
+}
+
+// sends MyEvent every second
+fn event_trigger_system(time: Res<Time>, mut my_events: EventWriter<MyEvent>) {
+    my_events.send(MyEvent {
+        message: format!(
+            "This event was sent at {}",
+            time.time_since_startup().as_millis()
+        )
+        .to_string(),
+    });
+}
+
+// reads events as soon as they come in
+fn event_listener_system(mut events: EventReader<MyEvent>) {
+    for _ in events.iter() {
+        info!("I heard an event!");
+    }
+}
+
+// reports events once every 5 seconds
+fn event_devourer_system(events: EventConsumer<MyEvent>) {
+    // Events are only consumed when .drain() is called
+    for my_event in events.drain() {
+        info!("{}", my_event.message);
+    }
+}