Minimal Bubbling Observers

[NthTensor]

Objective

Add basic bubbling to observers, modeled off bevy_eventlistener.

Solution

• Introduce a new Traversal trait for components which point to other entities.
• Provide a default TraverseNone: Traversal component which cannot be constructed.
• Implement Traversal for Parent.
• The Event trait now has an associated Traversal which defaults to TraverseNone.
• Added a field bubbling: &mut bool to Trigger which can be used to instruct the runner to bubble the event to the entity specified by the event's traversal type.
• Added an associated constant SHOULD_BUBBLE to Event which configures the default bubbling state.
• Added logic to wire this all up correctly.

Introducing the new associated information directly on Event (instead of a new BubblingEvent trait) lets us dispatch both bubbling and non-bubbling events through the same api.

Testing

I have added several unit tests to cover the common bugs I identified during development. Running the unit tests should be enough to validate correctness. The changes effect unsafe portions of the code, but should not change any of the safety assertions.

Changelog

Observers can now bubble up the entity hierarchy! To create a bubbling event, change your Derive(Event) to something like the following:

#[derive(Component)]
struct MyEvent;

impl Event for MyEvent {
    type Traverse = Parent; // This event will propagate up from child to parent.
    const AUTO_PROPAGATE: bool = true; // This event will propagate by default.
}

You can dispatch a bubbling event using the normal world.trigger_targets(MyEvent, entity).

Halting an event mid-bubble can be done using trigger.propagate(false). Events with AUTO_PROPAGATE = false will not propagate by default, but you can enable it using trigger.propagate(true).

If there are multiple observers attached to a target, they will all be triggered by bubbling. They all share a bubbling state, which can be accessed mutably using trigger.propagation_mut() (trigger.propagate is just sugar for this).

You can choose to implement Traversal for your own types, if you want to bubble along a different structure than provided by bevy_hierarchy. Implementers must be careful never to produce loops, because this will cause bevy to hang.

Migration Guide

• Manual implementations of Event should add associated type Traverse = TraverseNone and associated constant AUTO_PROPAGATE = false;
• Trigger::new has new field propagation: &mut Propagation which provides the bubbling state.
• ObserverRunner now takes the same &mut Propagation as a final parameter.

[MrGVSV]

Just a few typos on some internal test items (awesome tests btw!)

[Jondolf]

I'm not too familiar with the observer code (or ECS details in general), but I didn't spot any obvious issues based on a quick look. I mainly went through the docs and how this works at a high level.

The core implementation looks solid, and will definitely be highly useful for picking and UI, as well as many general patterns. I like that you can implement custom traversal: for example in bevy_xpbd, I have a ColliderParent component, and I could use it to propagate collision events from child colliders directly to rigid body entities.

I do agree with @MrGVSV that the current terminology is potentially misleading. Bubbling in my mind always goes up in the hierarchy, which is not necessarily the case for us if we allow custom traversal.

Overall I'd like to see some improvements to the documentation here: What is event bubbling? What could it be useful for? How do I stop propagation? What is Event::Traverse actually used for? How can I implement my own traversal? These are largely answered in the PR description, but I'd like it in the actual documentation.

[NthTensor]

I would like advice on how best to document this, since it doesn't really expose anything publicly by default, except for perhaps the new Traversal trait (which I am writing better docs for).

The docs entry-point for observers seems to be the Observer component. Does it make more sense to talk about this there, on Event or both?

[alice-i-cecile]

My preference is to primarily cover this on Traversal, but link to that trait's docs with a one sentence explanation of how / why this might be used in both Event and Observer's docs.

[NthTensor]

I resolved all the issues identified in the reviews and I was in the process of porting over the examples from bevy_eventlistener when I identified a rather large footgun with how global observers (ones who don't target a specific list of entities) interact with bubbling; eg, they don't.

I'll be rewriting this a bit over the next week to fix this issue.

[aevyrie]

Completely non-blocking - have you done any sort of performance profiling? I'm curious how this scales.

[NthTensor]

I have not yet profiled. I am expecting it to be somewhat slower. Will port over the eventlistener stress test once I fix the footguns.

[github-actions]

You added a new example but didn't add metadata for it. Please update the root Cargo.toml file.

[MiniaczQ]

Very elegant :)

[MiniaczQ]

simple fix is a Vec<str> where we can push observer "labels" when they execute and then verify with vec!["obs1", "obs2"]
it's only tests so it doesn't need to be "proper"

would that be alright?

[NthTensor]

Great, thank you! I prefer the bool as well, that's how I had it implemented before the first round of feedback.

I'll get this cleaned up, benchmarked, and ready for merge by next monday then.

When this is done, I'll spin up some issues for follow up work that we uncovered:

• Traversal should be changed to use QueryData as described here.
• The observers tests should be updated to use a hash-map of counters probably.
• Consider moving trigger_observers over to slices rather than iterators, to match the new version of trigger_observers_with_data.

[NthTensor]

Addressed review comments, added a benchmark, cleaned things up a bit.

Preliminary profiling indicates this is a regression compared to the best case of bevy_eventlisterner but (a) its unlikely to cause problems in production and (b) we expect to be able to improve perf at a later stage.

If this passes tests I think it's good for merge.

[alice-i-cecile]

Thank you to everyone involved with the authoring or reviewing of this PR! This work is relatively important and needs release notes! Head over to bevyengine/bevy-website#1657 if you'd like to help out.