bevyengine/bevy

bevy_picking

The picking core. Defines pointers, hit data, and the events that drive click/hover/drag interactions. Backend-agnostic — separate plugins (MeshPickingPlugin, SpritePickingPlugin, UiPickingPlugin) provide the actual hit testing.

Purpose

Picking is the chain "user moves a pointer → some entities are hit → events get dispatched in priority order." bevy_picking provides the data types and the dispatch loop; it doesn't know how to ray-cast a mesh or test against a UI rectangle. That logic lives in domain-specific picking backends.

Directory layout

crates/bevy_picking/src/
├── lib.rs                 # PickingPlugin (core)
├── pointer.rs             # PointerId, PointerLocation
├── hover.rs               # PointerInteraction, hover map
├── events.rs              # Click / Drag / DragStart / Out events
├── focus.rs               # Hover focus computation
├── input.rs               # Map raw input to pointer events
├── window.rs              # Per-window pointer mapping
├── backend.rs             # PickingBackend trait + ranking
└── …

Key abstractions

Type	File	Description
`Pointer` (entity component)	`crates/bevy_picking/src/pointer.rs`	A pointer (mouse, touch, gamepad).
`PointerId`	`crates/bevy_picking/src/pointer.rs`	ID for a pointer source.
`PickingBackend` (trait)	`crates/bevy_picking/src/backend.rs`	Backends implement hit testing for a domain.
`PointerInteraction`	`crates/bevy_picking/src/hover.rs`	Currently hovered entity per pointer.
`Pointer<E>` (event)	`crates/bevy_picking/src/events.rs`	Generic event type — `Pointer<Click>`, `Pointer<Drag>`, etc.
`PickingBehavior`	`crates/bevy_picking/src/lib.rs`	Per-entity opt-in / blocking behavior.

How it works

sequenceDiagram
    participant Input
    participant Pointers as PointerLocation
    participant Backends as Picking Backends
    participant Hover as Hover map
    participant User as Observer<Pointer<E>>

    Input->>Pointers: mouse / touch position
    Pointers->>Backends: ray, screen position
    Backends->>Hover: ranked HitData per pointer
    Hover->>User: Click / Drag / Hover events via observers

Each PickingBackend returns (Entity, HitData) lists per pointer. The core ranks hits by a per-backend priority and a depth value, then dispatches events through observers (the modern picking API uses Observer<Pointer<Click>> etc).

The high-level events (Click, Up, Down, Drag, DragStart, DragEnd, Over, Out, Move) are computed from raw pointer state changes.

Integration points

Depends on: bevy_app, bevy_ecs, bevy_math, bevy_input, bevy_window, bevy_camera, bevy_reflect.
Depended on by: bevy_sprite (sprite picking), bevy_pbr (mesh picking), bevy_ui (UI picking), bevy_dev_tools (picking debug overlay).

Entry points for modification

New backend: implement PickingBackend and add a system that fills PickingBackendOutput. Mesh, sprite, and UI backends are the templates.
New high-level event: edit events.rs. Compute it from raw state changes in state.rs.
Per-entity behavior: PickingBehavior controls whether picking is enabled and whether hits propagate.