Make 2D picking Z plane configurable (#982)

# Objective

- Even after #962, 2D picking only works reliably when pickable
colliders are located on the Z = 0 plane when e.g. using perspective
projection or a rotated camera. Allowing this Z coordinate to be
configured could be useful.

## Solution

- Make the Z level used for picking ray intersection configurable by
adding a new field to `PhysicsPickingSettings`.
- Extend the `picking_2d_in_perspective` example with controls for
moving the physics picking Z plane, rotating the camera, and switching
projection type, demonstrating this new functionality.
- Write a migration guide entry for the changes in this PR and #962.

## Testing

- The extended `picking_2d_in_perspective` example seems to work
properly.
- The solution works in my use case, picking from a 3D camera with
perspective projection and colliders located far away in negative Z,
which was previously broken.
- `cargo test` returns 4 failures, but I get the same result on the
latest commit before my changes.
  ```log
----
dynamics::rigid_body::mass_properties::tests::mass_properties_add_remove_collider
stdout ----
  
thread
'dynamics::rigid_body::mass_properties::tests::mass_properties_add_remove_collider'
(22023) panicked at
crates/avian2d/../../src/dynamics/rigid_body/mass_properties/mod.rs:736:9:
  assertion `left == right` failed
    left: 15.707963
   right: 15.707964
  
----
dynamics::rigid_body::mass_properties::tests::mass_properties_no_auto_mass_add_remove
stdout ----
  
thread
'dynamics::rigid_body::mass_properties::tests::mass_properties_no_auto_mass_add_remove'
(22026) panicked at
crates/avian2d/../../src/dynamics/rigid_body/mass_properties/mod.rs:890:9:
  assertion `left == right` failed
    left: 14.999999
   right: 15.0
  
----
dynamics::rigid_body::mass_properties::tests::mass_properties_move_child_collider
stdout ----
  
thread
'dynamics::rigid_body::mass_properties::tests::mass_properties_move_child_collider'
(22025) panicked at
crates/avian2d/../../src/dynamics/rigid_body/mass_properties/mod.rs:843:9:
  assertion `left == right` failed
    left: 14.999999
   right: 15.0
  
----
dynamics::rigid_body::mass_properties::tests::mass_properties_rb_collider_with_set_mass_and_child_collider_with_set_mass
stdout ----
  
thread
'dynamics::rigid_body::mass_properties::tests::mass_properties_rb_collider_with_set_mass_and_child_collider_with_set_mass'
(22033) panicked at
crates/avian2d/../../src/dynamics/rigid_body/mass_properties/mod.rs:629:9:
  assertion `left == right` failed
    left: 14.999999
   right: 15.0
  ```

All testing done was on x86_64-unknown-linux-gnu (latest CachyOS Desktop
as of writing, using the
[rust](https://packages.cachyos.org/package/cachyos-extra-znver4/x86_64_v4/rust)
package from the `cachyos-extra-znver4` distribution repository).

---------

Co-authored-by: Joona Aalto <jondolf.dev@gmail.com>

Author: Luracasmus

crates/avian2d/examples/picking_2d_in_perspective.rs

@@ -1,5 +1,5 @@
 use avian2d::{math::*, prelude::*};
-use bevy::prelude::*;
+use bevy::{camera::ScalingMode, prelude::*};
 use examples_common_2d::ExampleCommonPlugin;
 
 fn main() {
@@ -13,10 +13,14 @@ fn main() {
         .insert_resource(ClearColor(Color::srgb(0.05, 0.05, 0.1)))
         .insert_resource(Gravity(Vector::NEG_Y))
         .add_systems(Startup, setup)
-        .add_systems(Update, move_camera)
+        .add_systems(Update, control_camera_and_plane)
         .run();
 }
 
+#[derive(Component)]
+#[component(immutable)]
+struct PickingPlane;
+
 fn setup(
     mut commands: Commands,
     mut materials: ResMut<Assets<ColorMaterial>>,
@@ -29,154 +33,200 @@ fn setup(
         Transform::from_xyz(0.0, 0.0, 1.0), // We have to start slightly away from the Z axis, since now everything is drawing at Z = 0
     ));
 
-    let square_sprite = Sprite {
-        color: Color::srgb(0.7, 0.7, 0.8),
-        custom_size: Some(Vec2::splat(0.05)),
-        ..default()
-    };
-
-    // Ceiling
-    commands.spawn((
-        square_sprite.clone(),
-        Transform::from_xyz(0.0, 0.05 * 6.0, 0.0).with_scale(Vec3::new(20.0, 1.0, 1.0)),
-        RigidBody::Static,
-        Collider::rectangle(0.05, 0.05),
-    ));
-    // Floor
-    commands.spawn((
-        square_sprite.clone(),
-        Transform::from_xyz(0.0, -0.05 * 6.0, 0.0).with_scale(Vec3::new(20.0, 1.0, 1.0)),
-        RigidBody::Static,
-        Collider::rectangle(0.05, 0.05),
-    ));
-    // Left wall
-    commands.spawn((
-        square_sprite.clone(),
-        Transform::from_xyz(-0.05 * 9.5, 0.0, 0.0).with_scale(Vec3::new(1.0, 11.0, 1.0)),
-        RigidBody::Static,
-        Collider::rectangle(0.05, 0.05),
-    ));
-    // Right wall
-    commands.spawn((
-        square_sprite,
-        Transform::from_xyz(0.05 * 9.5, 0.0, 0.0).with_scale(Vec3::new(1.0, 11.0, 1.0)),
-        RigidBody::Static,
-        Collider::rectangle(0.05, 0.05),
-    ));
+    // For example purposes, define a custom picking plane that can be moved with the E and Q keys.
+    // Using a picking plane like this is not required, but the Z coordinates of 2D colliders
+    // should match `PhysicsPickingSettings::z_plane` for them to be picked at the correct XY coordinates.
+    commands
+        .spawn((PickingPlane, Visibility::Visible, Transform::default()))
+        .with_children(|child_spawner_commands| {
+            let square_sprite = Sprite {
+                color: Color::srgb(0.7, 0.7, 0.8),
+                custom_size: Some(Vec2::splat(0.05)),
+                ..default()
+            };
 
-    for flip in [-1.0, 1.0] {
-        // Static anchor for the churner
-        let velocity_anchor = commands
-            .spawn((
-                Sprite {
-                    color: Color::srgb(0.5, 0.5, 0.5),
-                    custom_size: Some(Vec2::splat(0.01)),
-                    ..default()
-                },
-                Transform::from_xyz(-0.3 * flip, -0.15, 0.0),
+            // Ceiling
+            child_spawner_commands.spawn((
+                square_sprite.clone(),
+                Transform::from_xyz(0.0, 0.05 * 6.0, 0.0).with_scale(Vec3::new(20.0, 1.0, 1.0)),
                 RigidBody::Static,
-            ))
-            .id();
-
-        // Spinning churner
-        let velocity_wheel = commands
-            .spawn((
-                Sprite {
-                    color: Color::srgb(0.9, 0.3, 0.3),
-                    custom_size: Some(vec2(0.24, 0.02)),
-                    ..default()
-                },
-                Transform::from_xyz(-0.3 * flip, -0.15, 0.0),
-                RigidBody::Dynamic,
-                Mass(1.0),
-                AngularInertia(1.0),
-                SleepingDisabled, // Prevent sleeping so motor can always control it
-                Collider::rectangle(0.24, 0.02),
-            ))
-            .id();
-
-        // Revolute joint with velocity-controlled motor
-        // Default anchors are at body centers (Vector::ZERO)
-        commands.spawn((
-            RevoluteJoint::new(velocity_anchor, velocity_wheel).with_motor(AngularMotor {
-                target_velocity: 5.0 * flip.adjust_precision(),
-                max_torque: 1000.0,
-                motor_model: MotorModel::AccelerationBased {
-                    stiffness: 0.0,
-                    damping: 1.0,
-                },
-                ..default()
-            }),
-        ));
-    }
+                Collider::rectangle(0.05, 0.05),
+            ));
+            // Floor
+            child_spawner_commands.spawn((
+                square_sprite.clone(),
+                Transform::from_xyz(0.0, -0.05 * 6.0, 0.0).with_scale(Vec3::new(20.0, 1.0, 1.0)),
+                RigidBody::Static,
+                Collider::rectangle(0.05, 0.05),
+            ));
+            // Left wall
+            child_spawner_commands.spawn((
+                square_sprite.clone(),
+                Transform::from_xyz(-0.05 * 9.5, 0.0, 0.0).with_scale(Vec3::new(1.0, 11.0, 1.0)),
+                RigidBody::Static,
+                Collider::rectangle(0.05, 0.05),
+            ));
+            // Right wall
+            child_spawner_commands.spawn((
+                square_sprite,
+                Transform::from_xyz(0.05 * 9.5, 0.0, 0.0).with_scale(Vec3::new(1.0, 11.0, 1.0)),
+                RigidBody::Static,
+                Collider::rectangle(0.05, 0.05),
+            ));
 
-    let circle = Circle::new(0.0075);
-    let collider = circle.collider();
-    let mesh = meshes.add(circle);
-
-    let ball_color = Color::srgb(0.29, 0.33, 0.64);
-
-    for x in -12i32..=12 {
-        for y in -1_i32..=8 {
-            commands
-                .spawn((
-                    Mesh2d(mesh.clone()),
-                    MeshMaterial2d(materials.add(ball_color)),
-                    Transform::from_xyz(x as f32 * 0.025, y as f32 * 0.025, 0.0),
-                    collider.clone(),
-                    RigidBody::Dynamic,
-                    Friction::new(0.1),
-                ))
-                .observe(
-                    |over: On<Pointer<Over>>,
-                     mut materials: ResMut<Assets<ColorMaterial>>,
-                     balls: Query<&MeshMaterial2d<ColorMaterial>>| {
-                        materials
-                            .get_mut(balls.get(over.entity).unwrap())
-                            .unwrap()
-                            .color = Color::WHITE;
-                    },
-                )
-                .observe(
-                    move |out: On<Pointer<Out>>,
-                          mut materials: ResMut<Assets<ColorMaterial>>,
-                          balls: Query<&MeshMaterial2d<ColorMaterial>>| {
-                        materials
-                            .get_mut(balls.get(out.entity).unwrap())
-                            .unwrap()
-                            .color = ball_color;
-                    },
-                );
-        }
-    }
+            for flip in [-1.0, 1.0] {
+                // Static anchor for the churner
+                let velocity_anchor = child_spawner_commands
+                    .spawn((
+                        Sprite {
+                            color: Color::srgb(0.5, 0.5, 0.5),
+                            custom_size: Some(Vec2::splat(0.01)),
+                            ..default()
+                        },
+                        Transform::from_xyz(-0.3 * flip, -0.15, 0.0),
+                        RigidBody::Static,
+                    ))
+                    .id();
+
+                // Spinning churner
+                let velocity_wheel = child_spawner_commands
+                    .spawn((
+                        Sprite {
+                            color: Color::srgb(0.9, 0.3, 0.3),
+                            custom_size: Some(vec2(0.24, 0.02)),
+                            ..default()
+                        },
+                        Transform::from_xyz(-0.3 * flip, -0.15, 0.0),
+                        RigidBody::Dynamic,
+                        Mass(1.0),
+                        AngularInertia(1.0),
+                        SleepingDisabled, // Prevent sleeping so motor can always control it
+                        Collider::rectangle(0.24, 0.02),
+                    ))
+                    .id();
+
+                // Revolute joint with velocity-controlled motor
+                // Default anchors are at body centers (Vector::ZERO)
+                child_spawner_commands.spawn((RevoluteJoint::new(velocity_anchor, velocity_wheel)
+                    .with_motor(AngularMotor {
+                        target_velocity: 5.0 * flip.adjust_precision(),
+                        max_torque: 1000.0,
+                        motor_model: MotorModel::AccelerationBased {
+                            stiffness: 0.0,
+                            damping: 1.0,
+                        },
+                        ..default()
+                    }),));
+            }
+
+            let circle = Circle::new(0.0075);
+            let collider = circle.collider();
+            let mesh = meshes.add(circle);
+
+            let ball_color = Color::srgb(0.29, 0.33, 0.64);
+
+            for x in -12i32..=12 {
+                for y in -1_i32..=8 {
+                    child_spawner_commands
+                        .spawn((
+                            Mesh2d(mesh.clone()),
+                            MeshMaterial2d(materials.add(ball_color)),
+                            Transform::from_xyz(x as f32 * 0.025, y as f32 * 0.025, 0.0),
+                            collider.clone(),
+                            RigidBody::Dynamic,
+                            Friction::new(0.1),
+                        ))
+                        .observe(
+                            |over: On<Pointer<Over>>,
+                             mut materials: ResMut<Assets<ColorMaterial>>,
+                             balls: Query<&MeshMaterial2d<ColorMaterial>>| {
+                                materials
+                                    .get_mut(balls.get(over.entity).unwrap())
+                                    .unwrap()
+                                    .color = Color::WHITE;
+                            },
+                        )
+                        .observe(
+                            move |out: On<Pointer<Out>>,
+                                  mut materials: ResMut<Assets<ColorMaterial>>,
+                                  balls: Query<&MeshMaterial2d<ColorMaterial>>| {
+                                materials
+                                    .get_mut(balls.get(out.entity).unwrap())
+                                    .unwrap()
+                                    .color = ball_color;
+                            },
+                        );
+                }
+            }
+        });
 }
 
 // TODO: if anyone would like to improve this example, a freecam could be fun to mess around with :D
-fn move_camera(
-    mut camera: Single<&mut Transform, With<Camera>>,
+fn control_camera_and_plane(
+    mut camera: Single<(&mut Transform, &mut Projection), With<Camera>>,
+    mut picking_plane: Single<&mut Transform, (With<PickingPlane>, Without<Camera>)>,
+    mut physics_picking_settings: ResMut<PhysicsPickingSettings>,
     input: Res<ButtonInput<KeyCode>>,
     time: Res<Time>,
 ) {
-    const MOVE_SCALE: f32 = 1.0;
+    const CAMERA_MOVE_SCALE: f32 = 1.0;
+    const CAMERA_ROTATE_SCALE: f32 = 1.0;
+    const PICKING_MOVE_SCALE: f32 = 1.0;
 
-    let mut delta = Vec3::ZERO;
+    let mut linear_delta = Vec3::ZERO;
     if input.pressed(KeyCode::KeyW) {
-        delta.z -= time.delta_secs() * MOVE_SCALE;
+        linear_delta.z -= CAMERA_MOVE_SCALE;
     }
     if input.pressed(KeyCode::KeyS) {
-        delta.z += time.delta_secs() * MOVE_SCALE;
+        linear_delta.z += CAMERA_MOVE_SCALE;
     }
     if input.pressed(KeyCode::KeyA) {
-        delta.x -= time.delta_secs() * MOVE_SCALE;
+        linear_delta.x -= CAMERA_MOVE_SCALE;
     }
     if input.pressed(KeyCode::KeyD) {
-        delta.x += time.delta_secs() * MOVE_SCALE;
+        linear_delta.x += CAMERA_MOVE_SCALE;
     }
     if input.pressed(KeyCode::ShiftLeft) {
-        delta.y -= time.delta_secs() * MOVE_SCALE;
+        linear_delta.y -= CAMERA_MOVE_SCALE;
     }
     if input.pressed(KeyCode::Space) {
-        delta.y += time.delta_secs() * MOVE_SCALE;
+        linear_delta.y += CAMERA_MOVE_SCALE;
+    }
+    let camera_rotation = camera.0.rotation;
+    camera.0.translation += camera_rotation * (time.delta_secs() * linear_delta);
+
+    let mut angular_delta = 0.0;
+    if input.pressed(KeyCode::ArrowRight) {
+        angular_delta -= CAMERA_ROTATE_SCALE;
+    }
+    if input.pressed(KeyCode::ArrowLeft) {
+        angular_delta += CAMERA_ROTATE_SCALE;
+    }
+    camera.0.rotate_y(time.delta_secs() * angular_delta);
+
+    let mut picking_plane_delta = 0.0;
+    if input.pressed(KeyCode::KeyE) {
+        picking_plane_delta += PICKING_MOVE_SCALE
+    }
+    if input.pressed(KeyCode::KeyQ) {
+        picking_plane_delta -= PICKING_MOVE_SCALE;
+    }
+    picking_plane_delta *= time.delta_secs();
+
+    physics_picking_settings.z_plane += picking_plane_delta;
+    picking_plane.translation.z += picking_plane_delta;
+
+    if input.just_pressed(KeyCode::KeyR) {
+        *camera.1 = if let Projection::Perspective(_) = *camera.1 {
+            Projection::Orthographic(OrthographicProjection {
+                scaling_mode: ScalingMode::AutoMin {
+                    min_width: 1.0,
+                    min_height: 1.0,
+                },
+                ..OrthographicProjection::default_3d()
+            })
+        } else {
+            Projection::Perspective(PerspectiveProjection::default())
+        }
     }
-    camera.translation += delta;
 }

migration-guides/0.6-to-main.md

@@ -17,6 +17,21 @@ simply ignore the new parameter with `_`.
 Similar to many other plugins, the `SpatialQueryPlugin` now stores a schedule label,
 which by default is also passed via `PhysicsPlugins::new`.
 
+## 2D picking works in more 3D situations
+
+PRs: [#982](https://github.com/avianphysics/avian/pull/982)
+
+`PhysicsPickingSettings` in 2D now contains a `z_plane` that determines the world space Z coordinate
+of the plane that rays cast from the picking `Camera` intersect, affecting the world space XY coordinates
+used when querying for colliders to pick.
+
+This allows 2D physics picking to work properly with cameras using perspective projection
+or rotated away from the default forward direction, as long as all pickable colliders
+are located at the `z_plane` world space Z coordinate.
+
+The Z component of the `HitData::position` produced when picking in 2D is now equal to `PhysicsPickingSettings::z_plane`,
+and `HitData::depth` is equal to the distance along each ray to its intersection point on the plane.
+
 ## Physics Debug Gizmo Mesh Visibility
 
 In past releases, `PhysicsGizmos::hide_meshes` forced all meshes to be visible when it is `false`.