3D Mouse Picking for Bevy

This is a 3D mouse picking plugin for Bevy. The plugin will cast a ray into the scene and check for intersection against all meshes tagged with the PickableMesh component. The built-in highlighting and selection state, as well as the debug cursor, are opt-in.

Out of the box, the plugin provides: pick depth, pick coordinates, and surface normal of the picked mesh triangle.

Expect Breaking Changes in master - Contributions Welcome

Picking demo

Getting Started

To run the 3d_scene example - a modified version of the Bevy example of the same name - clone this repository and run:

cargo run --example 3d_scene

Usage

Setup

Add the most recent crates.io release to your dependencies in Cargo.toml

bevy_mod_picking = "0.1.2"

Import the plugin:

use bevy_mod_picking::*;

Add it to your App::build() in the plugins section of your Bevy app:

.add_plugin(PickingPlugin)

Marking Entities for Picking

Make sure you have your camera's entity on hand, you could do the following in your setup system:

let camera_entity = commands
        .spawn(Camera3dComponents {
            ..Default::default()
        })
        .current_entity()
        .unwrap();

Now all you have to do is mark any mesh entities with the PickableMesh component:

.with(PickableMesh::new(camera_entity))

If you want it to highlight when you hover, add the HighlightablePickMesh component:

.with(HighlightablePickMesh::new())

If you also want to select meshes and keep them highlighted with the left mouse button, add the SelectablePickMesh component:

.with(SelectablePickMesh::new())

Getting Pick Data

Pick Intersections Under the Cursor

Mesh picking intersection are reported in world coordinates. You can use the PickState resource to either get the topmost entity, or a list of all entities sorted by distance (near -> far) under the cursor:

fn get_picks(
    pick_state: Res<PickState>,
) {
    println!("All entities:\n{:?}", pick_state.list());
    println!("Top entity:\n{:?}", pick_state.top());
}

Selection State

If you're using the SelectablePickMesh component for selection, you can access the selection state by querying all selectable entities and accessing the .selected() function.

Plugin Parameters

If you're using the built in HighlightablePickMash component for highlighting, you can change the colors by accessing the PickHighlightParams and setting the colors:

fn set_highlight_params(
    mut highlight_params: ResMut<PickHighlightParams>,
) {
    highlight_params.set_hover_color(Color::rgb(1.0, 0.0, 0.0));
    highlight_params.set_selection_color(Color::rgb(1.0, 0.0, 1.0));
}

Debug

You can also enable a debug cursor that will place a sphere at the intersection, with a tail pointing normal to the surface. Just add the DebugPickingPlugin to the App::build() in your Bevy program:

.add_plugin(DebugPickingPlugin)

bevy_mod_picking 0.1.2