Upstreaming bevy_eventlistener

[viridia]

In #9538 @cart has suggested that we could upstream bevy_eventlistener. @aevyrie Is willing to do the work, but needs guidance and assurance that this won't be wasted effort.

I'm opening this ticket to discuss the pros and cons of doing this, so that we can get consensus on how this is to be done. The design of bevy_eventlistener makes certain choices, and we really should examine each of those choices before going ahead. This is an invitation to post messages of support or rejection in the comments.

What problem does this solve or what need does it fill?

bevy_eventlistener provides a framework for "event bubbling", meaning that events can be targeted to a specific Entity, and (if the entity chooses not to handle the event) forwarded to its ancestors. This method of dispatching events is what virtually all modern UI frameworks do. Event bubbling is also used by other interactive systems besides UI. Having a common framework for doing this, assuming it can meet everyone's requirements, would make it easier to interact with scene elements and UI and reduce the number of overlapping solutions in the ecosystem.

What solution would you like?

Incorporation of bevy_eventlistener as an official Bevy crate.

What alternative(s) have you considered?

There are two alternatives:

1. Don't have an official sanctioned strategy for handling events, instead let each package handle events in their own way.
2. Adopt a different strategy for handling events.

Reasons not to upstream bevy_eventlistener

Here's some reasons why we might not want to adopt this package (at least not in its current form), I'm throwing these out for discussion, feel free to argue against them:

Single event handler vs. handler per event type

bevy_eventlistener defines event actions on a per-event-type basis - one handler for PointerUp, a different handler for PointerDown and so on. However, if you look at a framework like Xilem, it uses a single callback which accepts all event types, and then uses a match statement to dispatch the various types. This approach is more "Rust-like" and less "Web-like" just in general aesthetics. (It's also the approach seen in older desktop frameworks such as Java Swing).

The single event-handler approach has some limitations, but these may not be important. Using a match statement means that the set of possible events is closed, you can't add new events to the enum. In practice, however, adding new event types (at least in the web world) is extremely rare: most web frameworks only use the built-in event types, and custom events are handled via non-bubbling callbacks rather than event listeners.

Default bubbling

In general, 'bubbling' behavior is generally only used for built-in events such as pointer and keyboard events. Bubbling makes the most sense for events that are either spatial - meaning that the event is dispatched based on the mouse position, focus-based, or whose effects are otherwise tightly bound to some sub-graph of the hierarchy. Application-level events that represent state changes or semantic triggers generally do not bubble.

bevy_eventlistener bubbles events by default.

Alternative bubbling

bevy_eventlistener bubbles events by walking the chain of ECS entities, using the Parent/Child relationships. However, a UI framework might have a different notion of how events should be bubbled.

In particular, there's been a lot of discussion of how we might add support for entity relationships a la flecs. In this case, it seems natural that the UI hierarchy would be implemented in terms of these relationships.

The other possibility is that bubbling would occur not at the level of ECS relationships, but between "components" (in the React sense) which are not themselves entities but rather objects that generate entities. Although, I don't know of any frameworks that work like this so it may be a moot point.

Does picking need events?

The original motivation for bevy_eventlistener was to support picking of scene elements in bevy_mod_picking. However, picking doesn't necessarily have to be event-based: other frameworks (example: three.js) use a polling-based approach to picking, where the UI code calls a "get_element_under_cursor" method every frame.

Even though bevy_eventlistener does not in itself provide APIs for picking, using a polling-based approach to picking knocks out one of the supporting pillars for a common event library.

[IceSentry]

For the single event vs handler per event. I think we could still keep the support for generic event type but consolidate all point events under a single PointerEvent type. This keeps the flexibility of using eventlistener in other contexts or supporting custom events while keeping it more rust-like in the actual handler code.

[viridia]

You could go one step further and consolidate all "user input" events (pointer, keyboard, focus) events as an enum. So this would not include things like "animation complete" or "network offline". This means that most widgets would have a single closure for event handling. I think I'd prefer that, but I could go either way.

[aevyrie]

This discussion is about picking, not event listeners. The reason the events are separated is because it allows you to compose multiple callbacks on one entity, like adding a reusable hover callback on some entities and a reusable click callback on some others. If all pointer events have the same type, you can only have a single callback shared across all types. This also has a (potential) performance implication, because you lose the ability to accelerate the callback graph, because callbacks will be triggered for any pointer (or input) event. Regardless, the eventlistener crate supports either way of handling events.

[SanderMertens]

The other possibility is that bubbling would occur not at the level of ECS relationships, but between "components" (in the React sense) which are not themselves entities but rather objects that generate entities

Fwiw with the flecs analogue of React components (assemblies) relationships would still be used to bubble/propagate the event. Assembly instances are organized in a DOM-like tree, events should bubble up along the edges of this tree.

[aevyrie]

I had a discussion with Joy (I think? Sorry if I have the name wrong), about this. The conclusion we came to was that if bevy gets relations, we could essentially keep the same API used in bevy_eventlistener, but the backing storage for listeners would be global, instead of being stored in components.