bevy/crates
Miles Silberling-Cook 82128d778a
Picking event ordering (#14862)
# Objective

Correctly order picking events. Resolves
https://github.com/bevyengine/bevy/issues/5984.

## Solution

Event ordering [very long standing
problem](https://github.com/aevyrie/bevy_mod_picking/issues/294) with
mod picking, stemming from two related issues. The first problem was
that `Pointer<T>` events of different types couldn't be ordered, but we
have already gotten around that in the upstream by switching to
observers. Since observers run in the order they are triggered, this
isn't an issue.

The second problem was that the underlying event streams that picking
uses to create it's pointer interaction events *also* lacked ordering,
and the systems that generated the points couldn't interleave events.
This PR fixes that by unifying the event streams and integrating the
various interaction systems.

The concrete changes are as follows:
+ `bevy_winit::WinitEvent` has been moved to `bevy_window::WindowEvent`.
This provides a unified (and more importantly, *ordered*) input stream
for both `bevy_window` and `bevy_input` events.
+ Replaces `InputMove` and `InputPress` with `PointerInput`, a new
unified input event which drives picking and interaction. This event is
built to have drop-in forward compatibility with [winit's upcoming
pointer abstraction](https://github.com/rust-windowing/winit/pull/3876).
I have added code to emulate it using the current winit input
abstractions, but this entire thing will be much more robust when it
lands.
+ Rolls `pointer_events` `send_click_and_drag_events` and
`send_drag_over_events` into a single system, which operates directly on
`PointerEvent` and triggers observers as output.

The PR also improves docs and takes the opportunity to
refactor/streamline the pointer event dispatch logic.

## Status & Testing

This PR is now feature complete and documented. While it is
theoretically possible to add unit tests for the ordering, building the
picking mocking for that will take a little while.

Feedback on the chosen ordering of events is within-scope.

## Migration Guide

For users switching from `bevy_mod_picking` to `bevy_picking`:
+ Instead of adding an `On<T>` component, use `.observe(|trigger:
Trigger<T>|)`. You may now apply multiple handlers to the same entity
using this command.
+ Pointer interaction events now have semi-deterministic ordering which
(more or less) aligns with the order of the raw input stream. Consult
the docs on `bevy_picking::event::pointer_events` for current
information. You may need to adjust your event handling logic
accordingly.
+ `PointerCancel` has been replaced with `Pointer<Cancled>`, which now
has the semantics of an OS touch pointer cancel event.
+ `InputMove` and `InputPress` have been merged into `PointerInput`. The
use remains exactly the same.
+ Picking interaction events are now only accessible through observers,
and no `EventReader`. This functionality may be re-implemented later.

For users of `bevy_winit`:
+ The event `bevy_winit::WinitEvent` has moved to
`bevy_window::WindowEvent`. If this was the only thing you depended on
`bevy_winit` for, you should switch your dependency to `bevy_window`.
+ `bevy_window` now depends on `bevy_input`. The dependencies of
`bevy_input` are a subset of the existing dependencies for `bevy_window`
so this should be non-breaking.
2024-09-04 19:41:06 +00:00
..
bevy_a11y Add Reflect derive to bevy_a11y::Focus (#14763) 2024-08-15 17:33:20 +00:00
bevy_animation Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_app Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_asset Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_audio Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_color Color gradient curve (#14976) 2024-09-02 23:26:30 +00:00
bevy_core Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_core_pipeline Migrated NonZero* to NonZero<*> (#14978) 2024-08-30 02:37:47 +00:00
bevy_derive Remove deprecated bevy_dynamic_plugin (#14534) 2024-07-30 15:31:08 +00:00
bevy_dev_tools Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_diagnostic Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_dylib Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_ecs Opportunistically use dense iter for archetypal iteration in Par_iter (#14673) 2024-09-03 23:41:10 +00:00
bevy_encase_derive Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_gilrs Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_gizmos Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_gltf Apply unused_qualifications lint (#14828) 2024-08-21 12:29:33 +00:00
bevy_hierarchy Fix with_child not inserting Parent component (#15009) 2024-09-02 22:47:25 +00:00
bevy_input Fix common capitalization errors in documentation (#14562) 2024-07-31 21:16:05 +00:00
bevy_internal Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_log Updated LogPlugin Documentation with Performance Warning (#14984) 2024-09-03 00:48:19 +00:00
bevy_macro_utils Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_math Curve gizmos integration (#14971) 2024-08-29 16:48:22 +00:00
bevy_mikktspace Fix underflow panic in InitTriInfo (#14893) 2024-08-25 14:13:23 +00:00
bevy_pbr Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_picking Picking event ordering (#14862) 2024-09-04 19:41:06 +00:00
bevy_ptr Migrated NonZero* to NonZero<*> (#14978) 2024-08-30 02:37:47 +00:00
bevy_reflect Reflect SmolStr's De/Serialize implementation (#14982) 2024-09-02 22:35:17 +00:00
bevy_render Remove all existing system order ambiguities in DefaultPlugins (#15031) 2024-09-03 20:24:34 +00:00
bevy_scene reflect: implement the unique reflect rfc (#7207) 2024-08-12 17:01:41 +00:00
bevy_sprite Return Results from Camera's world/viewport conversion methods (#14989) 2024-09-03 19:45:15 +00:00
bevy_state Fix compile error caused by incorrect feature flag in bevy_state (#14987) 2024-08-30 18:57:08 +00:00
bevy_tasks Migrated NonZero* to NonZero<*> (#14978) 2024-08-30 02:37:47 +00:00
bevy_text Avoid reallocating spans buffer in TextPipeline (#15012) 2024-09-02 17:02:06 +00:00
bevy_time Allow ordering variable timesteps around fixed timesteps (#14881) 2024-08-23 16:19:42 +00:00
bevy_transform Generate links to definition in source code pages on docs.rs and dev-docs.bevyengine.org (#12965) 2024-07-29 23:10:16 +00:00
bevy_ui UI texture slice texture flipping reimplementation (#15034) 2024-09-04 19:31:41 +00:00
bevy_utils Replace bevy_utils::CowArc with atomicow (#14977) 2024-08-30 00:43:07 +00:00
bevy_window Picking event ordering (#14862) 2024-09-04 19:41:06 +00:00
bevy_winit Picking event ordering (#14862) 2024-09-04 19:41:06 +00:00