1 unstable release
0.20.2 | Oct 29, 2024 |
---|
#12 in #picking
145 downloads per month
7MB
493 lines
Picking and Pointer Events for Bevy
(Gbin: This is a fork just to support avian f64 for robotic simulations. As Bevy is getting first class support for picking, this should be a very temporary crate.)
lib.rs
:
A flexible set of plugins that add picking functionality to your bevy
app.
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 event
listeners, so you can attach On<Click>
components to an entity, to run a one-shot bevy system.
The plugin works with any input, including mouse, touch, pens, or virtual pointers controlled by
gamepads. It includes (optional) backends for rapier
, bevy_xpbd
, bevy_mod_raycast
,
bevy_ui
, bevy_sprite
, and egui
, that can be mixed and matched out of the box, or you can
write your own.
At its core, this crate provides a robust abstraction for computing picking state regardless of pointing devices, or what you are hit testing against.
Expressive Events
The plugin provides normal bevy events that can be listened to with EventReader
s. These
Pointer
events allow you to respond to interactions like Click
, Over
, or Drag
(13 pointer events are provided). However, this often causes boilerplate when you try to do
something in response to that click, and you want the behavior to be different depending on the
entity being clicked on.
This is where event listeners come in. Reacting to these interaction events on a specific entity
is made possible with the On<Event>
component. When events are generated, they bubble up
the entity hierarchy starting from their target, looking for these event listener components.
(See bevy_eventlistener
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((
// Spawn your entity here, e.g. a Mesh.
// When dragged, mutate the `Transform` component on the dragged target entity:
On::<Pointer<Drag>>::target_component_mut::<Transform>(|drag, transform| {
transform.rotate_local_y(drag.delta.x / 50.0)
}),
On::<Pointer<Click>>::add_command::<DeleteTarget>(),
On::<Pointer<Over>>::send_event::<Greeting>(),
));
}
If you don't need event bubbling or callbacks, you can respond to pointer events like you would
any other bevy event, using EventReader<Pointer<Click>>
, EventReader<Pointer<Move>>
, etc.
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. The plugin
also includes half a dozen backends out of the box. These include rapier
, bevy_xpbd
,
bevy_mod_raycast
, bevy_ui
, bevy_egui
, and bevy_sprite
.
Input Agnostic
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
Making objects pickable is pretty straightforward. In the most minimal cases, it's as simple as:
use bevy_mod_picking::prelude::*;
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(DefaultPickingPlugins); // Includes a mesh raycasting backend by default
commands.spawn((
PbrBundle::default(), // The raycasting backend works with meshes
PickableBundle::default(), // Makes the entity pickable, and adds optional features
));
commands.spawn(Camera3dBundle::default());
Next Steps
To learn more, take a look at the examples in the
./examples
directory. 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. All the types needed for
the pipeline are defined in the bevy_picking_core
crate.
Pointers (bevy_picking_core::pointer
)
The first stage of the pipeline is to gather inputs and update pointers. This stage is
ultimately responsible for generating InputMove
and
InputPress
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.
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 (bevy_picking_core::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 bevy_picking_core::backend
.
You will eventually need to choose which picking backend(s) you want to use. This plugin uses
bevy_mod_raycast
for 3d by default; it works with bevy Mesh
es out of the box and requires no
extra dependencies. These qualities make it useful when prototyping, however it might not be
performant enough for your use case. Consider switching to the rapier backend if performance
becomes a problem or if you already have the dependency in-tree. For many games, it may never be
an issue. You can find all the provided backends in the backends
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 (bevy_picking_core::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 Pickable
state of the entity. In other words, if one entity is
in front of another, usually only the topmost one will be hovered.
Events (bevy_picking_core::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. Once all events have been generated, the event bubbling
systems propagate events through the entity hierarchy, triggering On<E>
callbacks.
Because it is completely agnostic to the 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
~31–72MB
~1.5M SLoC