Use ColliderTrees for spatial queries (#941)

# Objective

Fixes #403.

#927 added `ColliderTrees` for the new BVH broad phase. We should reuse
them for spatial queries instead of maintaining and using a separate BVH
from Parry.

## Solution

In short:

- Add more traversal methods on `Bvh2` via extension traits (we should
probably upstream these)
- `sweep_traverse`, `sweep_traverse_miss`, `sweep_traverse_anyhit`, and
`sweep_traverse_dynamic`
  - `squared_distance_traverse` and `squared_distance_traverse_dynamic`
- Add methods for BVH traversal on `ColliderTree`
  - `ray_traverse_closest` and `ray_traverse_all`
  - `sweep_traverse_closest` and `sweep_traverse_all`
  - `squared_distance_traverse_closest`
  - `point_traverse`
  - `aabb_traverse`
- Remove `SpatialQueryPipeline`, and use the `ColliderTrees` traversal
methods for `SpatialQuery`

This involved some other miscellaneous changes:

- Shape casts now returns hits in arbitrary order when `max_hits > 1`,
similar to ray casts.
- `point2` and `normal2` were previously in local space, despite what
the docs state. They are now in world space.

## Testing

Tested different spatial queries in examples.

---

## Showcase

Before, updating the spatial query pipeline was extremely expensive for
large scenes with a lot of colliders:

<img width="263" height="439" alt="Before"
src="https://github.com/user-attachments/assets/0cc11950-cd69-434a-90f6-1fa517d255f9"
/>

(note that the tree optimization cost is partially hidden here, as it is
run in parallel with the spatial query pipeline update)

Now, using the much more optimized `ColliderTrees`, that overhead is
gone:

<img width="263" height="439" alt="After"
src="https://github.com/user-attachments/assets/e39091f1-3a6f-4cfd-b22d-c8ac9c646b5f"
/>

## Future Work

- Generic collider types for spatial queries (#810)

Author: Jondolf

Cargo.lock

@@ -90,6 +90,7 @@ approx = "0.5"
 parry2d = { version = "0.26", optional = true }
 parry2d-f64 = { version = "0.26", optional = true }
 obvhs = { version = "0.3" }
+obvhs_glam = { package = "glam", version = "0.31" }
 serde = { version = "1", features = ["derive"], optional = true }
 derive_more = "2"
 thiserror = "2"

crates/avian2d/Cargo.toml

@@ -92,6 +92,7 @@ approx = "0.5"
 parry3d = { version = "0.26", optional = true }
 parry3d-f64 = { version = "0.26", optional = true }
 obvhs = { version = "0.3" }
+obvhs_glam = { package = "glam", version = "0.31" }
 serde = { version = "1", features = ["derive"], optional = true }
 derive_more = "2"
 thiserror = "2"

crates/avian3d/Cargo.toml

@@ -257,7 +257,7 @@ fn update_camera_transform(
     accumulated_mouse_motion: Res<AccumulatedMouseMotion>,
     player: Single<(Entity, &Transform), With<TouchedEntities>>,
     mut camera: Single<&mut Transform, (With<Camera>, Without<TouchedEntities>)>,
-    spatial: Res<SpatialQueryPipeline>,
+    spatial: SpatialQuery,
 ) {
     let (player_entity, player_transform) = player.into_inner();
     let delta = accumulated_mouse_motion.delta;

crates/avian3d/examples/move_and_slide_3d.rs

@@ -6,7 +6,7 @@ since the latest release. These guides are evolving and may not be polished yet.
 See [migration-guides/README.md](./README.md) and existing entries for information about Avian's
 migration guide process and what to put here.
 
-## Broad Phase Rework
+## Broad Phase
 
 PR [#927](https://github.com/avianphysics/avian/pull/927) overhauled broad phase collision detection
 to use a Bounding Volume Hierarchy (BVH).
@@ -30,6 +30,32 @@ The order should still be deterministic across runs, given the same inputs.
 Previously, `ContactPair::body1` and `ContactPair::body2` also used the `Entity` of the collider
 if the collider was not attached to a body. Now, the properties are instead `None`.
 
+## Spatial Queries
+
+PR [#941](https://github.com/avianphysics/avian/pull/941) changed spatial queries to reuse
+the `ColliderTrees` used by the broad phase.
+
+### Removed `SpatialQueryPipeline`
+
+The `SpatialQueryPipeline` has been removed. Instead, use the `SpatialQuery` system parameter,
+or for lower level control, use the `ColliderTrees` resource directly.
+
+If you get query conflicts because `SpatialQuery` queries for `&Position` and `&Rotation` and your system
+also queries for them mutably, consider deferring the mutation to a later point to avoid the conflict.
+
+Previously, you could call `SpatialQuery::update_pipeline()` to update the internal acceleration structures
+when you have made changes to colliders or their positions, and need to perform spatial queries before the next physics step.
+This method no longer exists, but there is instead a public `update_moved_collider_aabbs` system that you can run.
+
+### Shape Cast Data
+
+Shape casts now return hits in arbitrary order when `max_hits > 1`, similar to ray casts.
+This is for performance reasons.
+
+Previously, `point2` in `ShapeHitData` was also relative to the shape cast origin,
+even though documentation described it as a global point. This has been fixed,
+and it is now in world space like the other values.
+
 ## Joint Motors
 
 `RevoluteJoint` and `PrismaticJoimt` now store motors for driving movement.

migration-guides/0.5-to-main.md

@@ -67,8 +67,8 @@ pub const COS_5_DEGREES: Scalar = 0.99619469809;
 #[doc(alias = "CollideAndSlide")]
 #[doc(alias = "StepSlide")]
 pub struct MoveAndSlide<'w, 's> {
-    /// The [`SpatialQueryPipeline`] used to perform spatial queries.
-    pub query_pipeline: Res<'w, SpatialQueryPipeline>,
+    /// The [`SpatialQuery`] system parameter used to perform shape casts and other geometric queries.
+    pub spatial_query: SpatialQuery<'w, 's>,
     /// The [`Query`] used to query for colliders.
     pub colliders: Query<
         'w,
@@ -538,7 +538,7 @@ impl<'w, 's> MoveAndSlide<'w, 's> {
                 position += sweep;
                 break;
             };
-            let point = sweep_hit.point2 + position;
+            let point = sweep_hit.point2;
 
             // Move up to the hit point.
             time_left -= time_left * (sweep_hit.distance / distance);
@@ -775,7 +775,7 @@ impl<'w, 's> MoveAndSlide<'w, 's> {
     ///
     /// # Related methods
     ///
-    /// - [`SpatialQueryPipeline::cast_shape`]
+    /// - [`SpatialQuery::cast_shape`]
     #[must_use]
     #[doc(alias = "sweep")]
     pub fn cast_move(
@@ -789,7 +789,7 @@ impl<'w, 's> MoveAndSlide<'w, 's> {
     ) -> Option<MoveHitData> {
         let (direction, distance) = Dir::new_and_length(movement.f32()).unwrap_or((Dir::X, 0.0));
         let distance = distance.adjust_precision();
-        let shape_hit = self.query_pipeline.cast_shape_predicate(
+        let shape_hit = self.spatial_query.cast_shape_predicate(
             shape,
             shape_position,
             shape_rotation,
@@ -1078,7 +1078,7 @@ impl<'w, 's> MoveAndSlide<'w, 's> {
             .aabb(shape_position, shape_rotation)
             .grow(Vector::splat(prediction_distance));
         let aabb_intersections = self
-            .query_pipeline
+            .spatial_query
             .aabb_intersections_with_aabb(expanded_aabb);
 
         'outer: for intersection_entity in aabb_intersections {

src/character_controller/move_and_slide.rs

@@ -22,16 +22,20 @@
 //! [`BvhBroadPhasePlugin`]: crate::collision::broad_phase::BvhBroadPhasePlugin
 
 mod diagnostics;
+mod obvhs_ext;
 mod optimization;
 mod proxy_key;
+mod traverse;
 mod tree;
 mod update;
 
 pub use diagnostics::ColliderTreeDiagnostics;
+pub use obvhs_ext::Bvh2Ext;
+pub(crate) use obvhs_ext::obvhs_ray;
 pub use optimization::{ColliderTreeOptimization, TreeOptimizationMode};
 pub use proxy_key::{ColliderTreeProxyKey, ColliderTreeType, ProxyId};
 pub use tree::{ColliderTree, ColliderTreeProxy, ColliderTreeProxyFlags, ColliderTreeWorkspace};
-pub use update::MovedProxies;
+pub use update::{MovedProxies, update_moved_collider_aabbs};
 
 use optimization::ColliderTreeOptimizationPlugin;
 use update::ColliderTreeUpdatePlugin;