Crate bevy_mod_picking
source ·Expand description
A flexible set of plugins that add picking functionality to your bevy
app, with a focus on
modularity, expressiveness, and robustness. Want to drag a UI entity and drop it onto a 3D mesh
entity? This plugin allows you to add event listeners to any entity, and works with mouse,
touch, or even gamepads. Includes optional integrations for rapier
and egui
, but is agnostic
to the picking backend.
Lightweight
Only compile what you use. All non-critical plugins can be disabled, including highlighting, selection, and any backends not in use.
Expressive
Pointer
events make it easy to react to interactions like Click
, Over
, or Drag
(13 pointer events are provided). 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.
This allows you to run callbacks when any children of an entity are interacted with:
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>(),
));
}
Modular
Picking backends run hit tests to determine if a pointer is over any entities. This plugin
provides a simple API to write your own backend in about 100 lines of code; it
also includes half a dozen backends out of the box. These include rapier
, bevy_mod_raycast
,
and bevy_egui
among others. Multiple backends can be used at the same time!
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.
Robust
In addition to these features, this plugin also correctly handles multitouch and multiple windows.
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);
commands.spawn((
PbrBundle::default(), // The `bevy_picking_raycast` backend works with meshes
PickableBundle::default(), // Makes the entity pickable
RaycastPickTarget::default() // Marker for the `bevy_picking_raycast` backend
));
commands.spawn((
Camera3dBundle::default(),
RaycastPickCamera::default(), // Enable picking using this camera
));
Next Steps
To learn more, take a look at the examples in the
./examples
directory.
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.
Input (bevy_picking_input
)
The first stage of the pipeline is to gather inputs and create 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 will eventually need to choose which picking backend(s) you want to use. This plugin uses
bevy_mod_raycast
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 is not particularly
performant for large meshes. Consider switching to the rapier backend if performance becomes a
problem or if you already have the dependency in-tree. For simple or low-poly games, it may
never be an issue.
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 entire bevy_mod_raycast
backend is less than 100
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 over an entity, the focus system needs to
determine which one(s) are actually being hovered 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, only the topmost one will be hovered, even if the pointer is
within the bounds of both entities.
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.
Re-exports
pub use bevy_picking_core as picking_core;
pub use bevy_picking_input as input;
pub use bevy_picking_highlight as highlight;
pub use bevy_picking_selection as selection;
Modules
- This module provides a simple interface for implementing a picking backend.
- Picking backend exports, feature-gated.
- Text and on-screen debugging tools
- Processes data from input and backends, producing interaction events.
- Determines which entities are being hovered by which pointers.
- Types and systems for pointer inputs, such as position and buttons.
- Common imports
Structs
- A “batteries-included” set of plugins that adds everything needed for picking, highlighting, and multiselect. Backends are automatically added if their corresponding feature is enabled.
- Makes an entity pickable.
- Bundle of components needed for a fully-featured pointer.