110 lines
19 KiB
HTML
110 lines
19 KiB
HTML
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="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."><title>bevy_picking - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../static.files/rustdoc-42caa33d.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="bevy_picking" data-themes="" data-resource-suffix="" data-rustdoc-version="1.84.0 (9fc6b4312 2025-01-07)" data-channel="1.84.0" data-search-js="search-92e6798f.js" data-settings-js="settings-0f613d39.js" ><script src="../static.files/storage-59e33391.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-044be391.svg"></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../bevy_picking/index.html">bevy_<wbr>picking</a><span class="version">0.15.1</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section id="rustdoc-toc"><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#overview" title="Overview">Overview</a></li><li><a href="#expressive-events" title="Expressive Events">Expressive Events</a></li><li><a href="#modularity" title="Modularity">Modularity</a><ul><li><a href="#mix-and-match-hit-testing-backends" title="Mix and Match Hit Testing Backends">Mix and Match Hit Testing Backends</a></li><li><a href="#input-agnostic" title="Input Agnostic">Input Agnostic</a></li></ul></li><li><a href="#robustness" title="Robustness">Robustness</a></li><li><a href="#getting-started" title="Getting Started">Getting Started</a><ul><li><a href="#next-steps" title="Next Steps">Next Steps</a></li></ul></li><li><a href="#the-picking-pipeline" title="The Picking Pipeline">The Picking Pipeline</a><ul><li><a href="#pointers-pointer" title="Pointers (`pointer`)">Pointers (<code>pointer</code>)</a></li><li><a href="#backend-backend" title="Backend (`backend`)">Backend (<code>backend</code>)</a></li><li><a href="#focus-focus" title="Focus (`focus`)">Focus (<code>focus</code>)</a></li><li><a href="#events-events" title="Events (`events`)">Events (<code>events</code>)</a></li></ul></li></ul><h3><a href="#modules">Crate Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#enums" title="Enums">Enums</a></li></ul></section><div id="rustdoc-modnav"></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <span>bevy_picking</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../src/bevy_picking/lib.rs.html#1-406">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>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.</p>
|
||
<h3 id="overview"><a class="doc-anchor" href="#overview">§</a>Overview</h3>
|
||
<p>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:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code>world.spawn(MyComponent)
|
||
.observe(|<span class="kw-2">mut </span>trigger: Trigger<Pointer<Click>>| {
|
||
<span class="comment">// Get the underlying event type
|
||
</span><span class="kw">let </span>click_event: <span class="kw-2">&</span>Pointer<Click> = trigger.event();
|
||
<span class="comment">// Stop the event from bubbling up the entity hierarchjy
|
||
</span>trigger.propagate(<span class="bool-val">false</span>);
|
||
});</code></pre></div>
|
||
<p>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.</p>
|
||
<h3 id="expressive-events"><a class="doc-anchor" href="#expressive-events">§</a>Expressive Events</h3>
|
||
<p>The events in this module (see <a href="events/index.html" title="mod bevy_picking::events"><code>events</code></a>) cannot be listened to with normal <code>EventReader</code>s.
|
||
Instead, they are dispatched to <em>observers</em> 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 halted
|
||
with a call to <a href="../bevy_ecs/observer/struct.Trigger.html#method.propagate" title="method bevy_ecs::observer::Trigger::propagate"><code>Trigger::propagate</code></a>.
|
||
See <a href="../bevy_ecs/observer/runner/struct.Observer.html" title="struct bevy_ecs::observer::runner::Observer"><code>Observer</code></a> for details.</p>
|
||
<p>This allows you to run callbacks when any children of an entity are interacted with, and leads
|
||
to succinct, expressive code:</p>
|
||
|
||
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">fn </span>setup(<span class="kw-2">mut </span>commands: Commands) {
|
||
commands.spawn(Transform::default())
|
||
<span class="comment">// Spawn your entity here, e.g. a Mesh.
|
||
// When dragged, mutate the `Transform` component on the dragged target entity:
|
||
</span>.observe(|trigger: Trigger<Pointer<Drag>>, <span class="kw-2">mut </span>transforms: Query<<span class="kw-2">&mut </span>Transform>| {
|
||
<span class="kw">let </span><span class="kw-2">mut </span>transform = transforms.get_mut(trigger.entity()).unwrap();
|
||
<span class="kw">let </span>drag = trigger.event();
|
||
transform.rotate_local_y(drag.delta.x / <span class="number">50.0</span>);
|
||
})
|
||
.observe(|trigger: Trigger<Pointer<Click>>, <span class="kw-2">mut </span>commands: Commands| {
|
||
<span class="macro">println!</span>(<span class="string">"Entity {:?} goes BOOM!"</span>, trigger.entity());
|
||
commands.entity(trigger.entity()).despawn();
|
||
})
|
||
.observe(|trigger: Trigger<Pointer<Over>>, <span class="kw-2">mut </span>events: EventWriter<Greeting>| {
|
||
events.send(Greeting);
|
||
});
|
||
}</code></pre></div>
|
||
<h3 id="modularity"><a class="doc-anchor" href="#modularity">§</a>Modularity</h3><h5 id="mix-and-match-hit-testing-backends"><a class="doc-anchor" href="#mix-and-match-hit-testing-backends">§</a>Mix and Match Hit Testing Backends</h5>
|
||
<p>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! <a href="backend/index.html" title="mod bevy_picking::backend">Use this
|
||
simple API to write your own backend</a> in about 100 lines of code.</p>
|
||
<h5 id="input-agnostic"><a class="doc-anchor" href="#input-agnostic">§</a>Input Agnostic</h5>
|
||
<p>Picking provides a generic Pointer abstraction, which is useful for reacting to many different
|
||
types of input devices. Pointers can be controlled with anything, whether it’s the included mouse
|
||
or touch inputs, or a custom gamepad input system you write yourself to control a virtual pointer.</p>
|
||
<h3 id="robustness"><a class="doc-anchor" href="#robustness">§</a>Robustness</h3>
|
||
<p>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.</p>
|
||
<h2 id="getting-started"><a class="doc-anchor" href="#getting-started">§</a>Getting Started</h2>
|
||
<p>TODO: This section will need to be re-written once more backends are introduced.</p>
|
||
<h5 id="next-steps"><a class="doc-anchor" href="#next-steps">§</a>Next Steps</h5>
|
||
<p>To learn more, take a look at the examples in the
|
||
<a href="https://github.com/bevyengine/bevy/tree/main/examples/picking">examples</a>. You
|
||
can read the next section to understand how the plugin works.</p>
|
||
<h2 id="the-picking-pipeline"><a class="doc-anchor" href="#the-picking-pipeline">§</a>The Picking Pipeline</h2>
|
||
<p>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.</p>
|
||
<h5 id="pointers-pointer"><a class="doc-anchor" href="#pointers-pointer">§</a>Pointers (<a href="pointer/index.html" title="mod bevy_picking::pointer"><code>pointer</code></a>)</h5>
|
||
<p>The first stage of the pipeline is to gather inputs and update pointers. This stage is
|
||
ultimately responsible for generating <a href="pointer/struct.PointerInput.html" title="struct bevy_picking::pointer::PointerInput"><code>PointerInput</code></a> 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
|
||
<a href="pointer/struct.PointerInput.html" title="struct bevy_picking::pointer::PointerInput"><code>PointerInput</code></a> stream is meaningful for events with the same
|
||
<a href="pointer/enum.PointerId.html" title="enum bevy_picking::pointer::PointerId"><code>PointerId</code></a>, but not between different pointers.</p>
|
||
<p>Because pointer positions and presses are driven by these events, you can use them to mock
|
||
inputs for testing.</p>
|
||
<p>After inputs are generated, they are then collected to update the current
|
||
<a href="pointer/struct.PointerLocation.html" title="struct bevy_picking::pointer::PointerLocation"><code>PointerLocation</code></a> for each pointer.</p>
|
||
<h5 id="backend-backend"><a class="doc-anchor" href="#backend-backend">§</a>Backend (<a href="backend/index.html" title="mod bevy_picking::backend"><code>backend</code></a>)</h5>
|
||
<p>A picking backend only has one job: reading <a href="pointer/struct.PointerLocation.html" title="struct bevy_picking::pointer::PointerLocation"><code>PointerLocation</code></a> components,
|
||
and producing <a href="backend/struct.PointerHits.html" title="struct bevy_picking::backend::PointerHits"><code>PointerHits</code></a>. You can find all documentation and types needed to
|
||
implement a backend at <a href="backend/index.html" title="mod bevy_picking::backend"><code>backend</code></a>.</p>
|
||
<p>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 <a href="backend/index.html" title="mod bevy_picking::backend"><code>backend</code></a> module.</p>
|
||
<p>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 <code>bevy_mod_raycast</code> backend is 50 lines of code.</p>
|
||
<h5 id="focus-focus"><a class="doc-anchor" href="#focus-focus">§</a>Focus (<a href="focus/index.html" title="mod bevy_picking::focus"><code>focus</code></a>)</h5>
|
||
<p>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 <a href="focus/struct.HoverMap.html" title="struct bevy_picking::focus::HoverMap"><code>HoverMap</code></a>. Note that
|
||
just because a pointer is over an entity, it is not necessarily <em>hovering</em> 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 <a href="struct.PickingBehavior.html" title="struct bevy_picking::PickingBehavior"><code>PickingBehavior</code></a> component of the entity. In other words,
|
||
if one entity is in front of another, usually only the topmost one will be hovered.</p>
|
||
<h5 id="events-events"><a class="doc-anchor" href="#events-events">§</a>Events (<a href="events/index.html" title="mod bevy_picking::events"><code>events</code></a>)</h5>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="backend/index.html" title="mod bevy_picking::backend">backend</a></div><div class="desc docblock-short">This module provides a simple interface for implementing a picking backend.</div></li><li><div class="item-name"><a class="mod" href="events/index.html" title="mod bevy_picking::events">events</a></div><div class="desc docblock-short">This module defines a stateful set of interaction events driven by the <code>PointerInput</code> stream
|
||
and the hover state of each Pointer.</div></li><li><div class="item-name"><a class="mod" href="focus/index.html" title="mod bevy_picking::focus">focus</a></div><div class="desc docblock-short">Determines which entities are being hovered by which pointers.</div></li><li><div class="item-name"><a class="mod" href="input/index.html" title="mod bevy_picking::input">input</a></div><div class="desc docblock-short">This module provides unsurprising default inputs to <code>bevy_picking</code> through <a href="pointer/struct.PointerInput.html" title="struct bevy_picking::pointer::PointerInput"><code>PointerInput</code></a>.
|
||
The included systems are responsible for sending mouse and touch inputs to their
|
||
respective <code>Pointer</code>s.</div></li><li><div class="item-name"><a class="mod" href="mesh_picking/index.html" title="mod bevy_picking::mesh_picking">mesh_<wbr>picking</a></div><div class="desc docblock-short">A <a href="mesh_picking/ray_cast/index.html" title="mod bevy_picking::mesh_picking::ray_cast">mesh ray casting</a> backend for <a href="index.html" title="mod bevy_picking"><code>bevy_picking</code></a>.</div></li><li><div class="item-name"><a class="mod" href="pointer/index.html" title="mod bevy_picking::pointer">pointer</a></div><div class="desc docblock-short">Types and systems for pointer inputs, such as position and buttons.</div></li><li><div class="item-name"><a class="mod" href="prelude/index.html" title="mod bevy_picking::prelude">prelude</a></div><div class="desc docblock-short">The picking prelude.</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.DefaultPickingPlugins.html" title="struct bevy_picking::DefaultPickingPlugins">Default<wbr>Picking<wbr>Plugins</a></div><div class="desc docblock-short">One plugin that contains the <a href="input/struct.PointerInputPlugin.html" title="struct bevy_picking::input::PointerInputPlugin"><code>PointerInputPlugin</code></a>, <a href="struct.PickingPlugin.html" title="struct bevy_picking::PickingPlugin"><code>PickingPlugin</code></a>
|
||
and the <a href="struct.InteractionPlugin.html" title="struct bevy_picking::InteractionPlugin"><code>InteractionPlugin</code></a>, this is probably the plugin that will be most used.</div></li><li><div class="item-name"><a class="struct" href="struct.InteractionPlugin.html" title="struct bevy_picking::InteractionPlugin">Interaction<wbr>Plugin</a></div><div class="desc docblock-short">Generates <a href="events/struct.Pointer.html" title="struct bevy_picking::events::Pointer"><code>Pointer</code></a> events and handles event bubbling.</div></li><li><div class="item-name"><a class="struct" href="struct.PickingBehavior.html" title="struct bevy_picking::PickingBehavior">Picking<wbr>Behavior</a></div><div class="desc docblock-short">An optional component that overrides default picking behavior for an entity, allowing you to
|
||
make an entity non-hoverable, or allow items below it to be hovered. See the documentation on
|
||
the fields for more details.</div></li><li><div class="item-name"><a class="struct" href="struct.PickingPlugin.html" title="struct bevy_picking::PickingPlugin">Picking<wbr>Plugin</a></div><div class="desc docblock-short">This plugin sets up the core picking infrastructure. It receives input events, and provides the shared
|
||
types used by other picking plugins.</div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.PickSet.html" title="enum bevy_picking::PickSet">PickSet</a></div><div class="desc docblock-short">Groups the stages of the picking process under shared labels.</div></li></ul></section></div></main></body></html> |