3 unstable releases
0.15.0-rc.2 | Oct 27, 2024 |
---|---|
0.15.0-rc.1 | Oct 22, 2024 |
0.0.1 | Sep 17, 2020 |
#1545 in Hardware support
1,182 downloads per month
7MB
122K
SLoC
Bevy Picking
lib.rs
:
This crate provides 'picking' capabilities for the Bevy game engine. That means, in simple terms, figuring out how to connect up a user's clicks or taps to the entities they are trying to interact with.
Overview
In the simplest case, this plugin allows you to click on things in the scene. However, it also allows you to express more complex interactions, like detecting when a touch input drags a UI element and drops it on a 3d mesh rendered to a different camera. The crate also provides a set of interaction callbacks, allowing you to receive input directly on entities like here:
world.spawn(MyComponent)
.observe(|mut trigger: Trigger<Pointer<Click>>| {
// Get the underlying event type
let click_event: &Pointer<Click> = trigger.event();
// Stop the event from bubbling up the entity hierarchjy
trigger.propagate(false);
});
At its core, this crate provides a robust abstraction for computing picking state regardless of pointing devices, or what you are hit testing against. It is designed to work with any input, including mouse, touch, pens, or virtual pointers controlled by gamepads.
Expressive Events
The events in this module (see events
) cannot be listened to with normal EventReader
s.
Instead, they are dispatched to ovservers attached to specific entities. When events are generated, they
bubble up the entity hierarchy starting from their target, until they reach the root or bubbling is haulted
with a call to Trigger::propagate
.
See Observer
for details.
This allows you to run callbacks when any children of an entity are interacted with, and leads to succinct, expressive code:
fn setup(mut commands: Commands) {
commands.spawn(Transform::default())
// Spawn your entity here, e.g. a Mesh.
// When dragged, mutate the `Transform` component on the dragged target entity:
.observe(|trigger: Trigger<Pointer<Drag>>, mut transforms: Query<&mut Transform>| {
let mut transform = transforms.get_mut(trigger.entity()).unwrap();
let drag = trigger.event();
transform.rotate_local_y(drag.delta.x / 50.0);
})
.observe(|trigger: Trigger<Pointer<Click>>, mut commands: Commands| {
println!("Entity {:?} goes BOOM!", trigger.entity());
commands.entity(trigger.entity()).despawn();
})
.observe(|trigger: Trigger<Pointer<Over>>, mut events: EventWriter<Greeting>| {
events.send(Greeting);
});
}
Modularity
Mix and Match Hit Testing Backends
The plugin attempts to handle all the hard parts for you, all you need to do is tell it when a pointer is hitting any entities. Multiple backends can be used at the same time! Use this simple API to write your own backend in about 100 lines of code.
Input Agnostic
Picking provides a generic Pointer abstracton, which is useful for reacting to many different types of input devices. Pointers can be controlled with anything, whether its the included mouse or touch inputs, or a custom gamepad input system you write yourself to control a virtual pointer.
Robustness
In addition to these features, this plugin also correctly handles multitouch, multiple windows, multiple cameras, viewports, and render layers. Using this as a library allows you to write a picking backend that can interoperate with any other picking backend.
Getting Started
TODO: This section will need to be re-written once more backends are introduced.
Next Steps
To learn more, take a look at the examples in the examples. You can read the next section to understand how the plugin works.
The Picking Pipeline
This plugin is designed to be extremely modular. To do so, it works in well-defined stages that form a pipeline, where events are used to pass data between each stage.
Pointers (pointer
)
The first stage of the pipeline is to gather inputs and update pointers. This stage is
ultimately responsible for generating PointerInput
events. The provided
crate does this automatically for mouse, touch, and pen inputs. If you wanted to implement your own
pointer, controlled by some other input, you can do that here. The ordering of events within the
PointerInput
stream is meaningful for events with the same
PointerId
, but not between different pointers.
Because pointer positions and presses are driven by these events, you can use them to mock inputs for testing.
After inputs are generated, they are then collected to update the current
PointerLocation
for each pointer.
Backend (backend
)
A picking backend only has one job: reading PointerLocation
components,
and producing PointerHits
. You can find all documentation and types needed to
implement a backend at backend
.
You will eventually need to choose which picking backend(s) you want to use. This crate does not
supply any backends, and expects you to select some from the other bevy crates or the third-party
ecosystem. You can find all the provided backends in the backend
module.
It's important to understand that you can mix and match backends! For example, you might have a
backend for your UI, and one for the 3d scene, with each being specialized for their purpose.
This crate provides some backends out of the box, but you can even write your own. It's been
made as easy as possible intentionally; the bevy_mod_raycast
backend is 50 lines of code.
Focus (focus
)
The next step is to use the data from the backends, combine and sort the results, and determine
what each cursor is hovering over, producing a HoverMap
. Note that
just because a pointer is over an entity, it is not necessarily hovering that entity. Although
multiple backends may be reporting that a pointer is hitting an entity, the focus system needs
to determine which entities are actually being hovered by this pointer based on the pick depth,
order of the backend, and the optional PickingBehavior
component of the entity. In other words,
if one entity is in front of another, usually only the topmost one will be hovered.
Events (events
)
In the final step, the high-level pointer events are generated, such as events that trigger when a pointer hovers or clicks an entity. These simple events are then used to generate more complex events for dragging and dropping.
Because it is completely agnostic to the earlier stages of the pipeline, you can easily extend the plugin with arbitrary backends and input methods, yet still use all the high level features.
Dependencies
~26–59MB
~1M SLoC