[add] physics collision filter backend support

Author: vmarcella

crates/lambda-rs-platform/src/physics/rapier2d.rs

@@ -304,6 +304,8 @@ impl PhysicsBackend2D {
   /// - `density`: The density in kg/m².
   /// - `friction`: The friction coefficient (unitless).
   /// - `restitution`: The restitution coefficient in `[0.0, 1.0]`.
+  /// - `collision_group`: The collider membership bitfield.
+  /// - `collision_mask`: The collider interaction mask bitfield.
   ///
   /// # Returns
   /// Returns a `(slot_index, slot_generation)` pair for the created collider.
@@ -322,6 +324,8 @@ impl PhysicsBackend2D {
     density: f32,
     friction: f32,
     restitution: f32,
+    collision_group: u32,
+    collision_mask: u32,
   ) -> Result<(u32, u32), Collider2DBackendError> {
     return self.attach_collider_2d(
       parent_slot_index,
@@ -332,6 +336,8 @@ impl PhysicsBackend2D {
       density,
       friction,
       restitution,
+      collision_group,
+      collision_mask,
     );
   }
 
@@ -350,6 +356,8 @@ impl PhysicsBackend2D {
   /// - `density`: The density in kg/m².
   /// - `friction`: The friction coefficient (unitless).
   /// - `restitution`: The restitution coefficient in `[0.0, 1.0]`.
+  /// - `collision_group`: The collider membership bitfield.
+  /// - `collision_mask`: The collider interaction mask bitfield.
   ///
   /// # Returns
   /// Returns a `(slot_index, slot_generation)` pair for the created collider.
@@ -369,6 +377,8 @@ impl PhysicsBackend2D {
     density: f32,
     friction: f32,
     restitution: f32,
+    collision_group: u32,
+    collision_mask: u32,
   ) -> Result<(u32, u32), Collider2DBackendError> {
     return self.attach_collider_2d(
       parent_slot_index,
@@ -379,6 +389,8 @@ impl PhysicsBackend2D {
       density,
       friction,
       restitution,
+      collision_group,
+      collision_mask,
     );
   }
 
@@ -398,6 +410,8 @@ impl PhysicsBackend2D {
   /// - `density`: The density in kg/m².
   /// - `friction`: The friction coefficient (unitless).
   /// - `restitution`: The restitution coefficient in `[0.0, 1.0]`.
+  /// - `collision_group`: The collider membership bitfield.
+  /// - `collision_mask`: The collider interaction mask bitfield.
   ///
   /// # Returns
   /// Returns a `(slot_index, slot_generation)` pair for the created collider.
@@ -417,6 +431,8 @@ impl PhysicsBackend2D {
     density: f32,
     friction: f32,
     restitution: f32,
+    collision_group: u32,
+    collision_mask: u32,
   ) -> Result<(u32, u32), Collider2DBackendError> {
     let rapier_builder = if half_height == 0.0 {
       ColliderBuilder::ball(radius)
@@ -433,6 +449,8 @@ impl PhysicsBackend2D {
       density,
       friction,
       restitution,
+      collision_group,
+      collision_mask,
     );
   }
 
@@ -452,6 +470,8 @@ impl PhysicsBackend2D {
   /// - `density`: The density in kg/m².
   /// - `friction`: The friction coefficient (unitless).
   /// - `restitution`: The restitution coefficient in `[0.0, 1.0]`.
+  /// - `collision_group`: The collider membership bitfield.
+  /// - `collision_mask`: The collider interaction mask bitfield.
   ///
   /// # Returns
   /// Returns a `(slot_index, slot_generation)` pair for the created collider.
@@ -472,6 +492,8 @@ impl PhysicsBackend2D {
     density: f32,
     friction: f32,
     restitution: f32,
+    collision_group: u32,
+    collision_mask: u32,
   ) -> Result<(u32, u32), Collider2DBackendError> {
     let rapier_vertices: Vec<Vector> = vertices
       .iter()
@@ -493,6 +515,8 @@ impl PhysicsBackend2D {
       density,
       friction,
       restitution,
+      collision_group,
+      collision_mask,
     );
   }
 
@@ -1018,6 +1042,8 @@ impl PhysicsBackend2D {
   /// - `density`: The requested density in kg/m².
   /// - `friction`: The friction coefficient (unitless).
   /// - `restitution`: The restitution coefficient in `[0.0, 1.0]`.
+  /// - `collision_group`: The collider membership bitfield.
+  /// - `collision_mask`: The collider interaction mask bitfield.
   ///
   /// # Returns
   /// Returns a `(slot_index, slot_generation)` pair for the created collider.
@@ -1035,13 +1061,17 @@ impl PhysicsBackend2D {
     density: f32,
     friction: f32,
     restitution: f32,
+    collision_group: u32,
+    collision_mask: u32,
   ) -> Result<(u32, u32), Collider2DBackendError> {
     let (rapier_parent_handle, rapier_density) = self
       .prepare_parent_body_for_collider_attachment_2d(
         parent_slot_index,
         parent_slot_generation,
         density,
       )?;
+    let interaction_groups =
+      build_collision_groups_2d(collision_group, collision_mask);
 
     let rapier_collider = rapier_builder
       .translation(Vector::new(local_offset[0], local_offset[1]))
@@ -1051,6 +1081,8 @@ impl PhysicsBackend2D {
       .friction_combine_rule(CoefficientCombineRule::Multiply)
       .restitution(restitution)
       .restitution_combine_rule(CoefficientCombineRule::Max)
+      .collision_groups(interaction_groups)
+      .solver_groups(interaction_groups)
       .build();
 
     let rapier_handle = self.colliders.insert_with_parent(
@@ -1251,6 +1283,25 @@ fn build_rapier_rigid_body(
   }
 }
 
+/// Converts public collision filter bitfields into Rapier interaction groups.
+///
+/// # Arguments
+/// - `collision_group`: The collider membership bitfield.
+/// - `collision_mask`: The collider interaction mask bitfield.
+///
+/// # Returns
+/// Returns Rapier interaction groups using AND-based matching.
+fn build_collision_groups_2d(
+  collision_group: u32,
+  collision_mask: u32,
+) -> InteractionGroups {
+  return InteractionGroups::new(
+    Group::from_bits_retain(collision_group),
+    Group::from_bits_retain(collision_mask),
+    InteractionTestMode::And,
+  );
+}
+
 /// Validates a 2D position.
 ///
 /// # Arguments

crates/lambda-rs/src/physics/collider_2d.rs

@@ -345,6 +345,8 @@ impl Collider2DBuilder {
           self.material.density(),
           self.material.friction(),
           self.material.restitution(),
+          self.collision_filter.group,
+          self.collision_filter.mask,
         )
         .map_err(map_backend_error)?,
       ColliderShape2D::Rectangle {
@@ -362,6 +364,8 @@ impl Collider2DBuilder {
           self.material.density(),
           self.material.friction(),
           self.material.restitution(),
+          self.collision_filter.group,
+          self.collision_filter.mask,
         )
         .map_err(map_backend_error)?,
       ColliderShape2D::Capsule {
@@ -379,6 +383,8 @@ impl Collider2DBuilder {
           self.material.density(),
           self.material.friction(),
           self.material.restitution(),
+          self.collision_filter.group,
+          self.collision_filter.mask,
         )
         .map_err(map_backend_error)?,
       ColliderShape2D::ConvexPolygon { vertices } => world
@@ -392,6 +398,8 @@ impl Collider2DBuilder {
           self.material.density(),
           self.material.friction(),
           self.material.restitution(),
+          self.collision_filter.group,
+          self.collision_filter.mask,
         )
         .map_err(map_backend_error)?,
     };

crates/lambda-rs/tests/physics_2d/collision_filters.rs

@@ -0,0 +1,148 @@
+//! 2D collision filter integration tests.
+//!
+//! These tests validate that collider group and mask settings affect physical
+//! contact generation through the public API.
+
+use lambda::physics::{
+  Collider2DBuilder,
+  CollisionFilter,
+  PhysicsWorld2D,
+  PhysicsWorld2DBuilder,
+  RigidBody2D,
+  RigidBody2DBuilder,
+  RigidBodyType,
+};
+
+const DEFAULT_STEP_COUNT: u32 = 240;
+
+/// Steps a world forward for the given number of fixed timesteps.
+///
+/// # Arguments
+/// - `world`: The world to step.
+/// - `steps`: The number of steps to execute.
+///
+/// # Returns
+/// Returns `()` after stepping the world.
+fn step_world(world: &mut PhysicsWorld2D, steps: u32) {
+  for _ in 0..steps {
+    world.step();
+  }
+
+  return;
+}
+
+/// Creates a static ground body with the provided collision filter.
+///
+/// # Arguments
+/// - `world`: The world that will own the body.
+/// - `filter`: The collision filter to apply to the ground collider.
+///
+/// # Returns
+/// Returns the created rigid body handle.
+fn build_ground(
+  world: &mut PhysicsWorld2D,
+  filter: CollisionFilter,
+) -> RigidBody2D {
+  let ground = RigidBody2DBuilder::new(RigidBodyType::Static)
+    .with_position(0.0, -1.0)
+    .build(world)
+    .unwrap();
+
+  Collider2DBuilder::rectangle(20.0, 0.5)
+    .with_collision_filter(filter)
+    .build(world, ground)
+    .unwrap();
+
+  return ground;
+}
+
+/// Creates a dynamic ball body with the provided collision filter.
+///
+/// # Arguments
+/// - `world`: The world that will own the body.
+/// - `filter`: The collision filter to apply to the ball collider.
+///
+/// # Returns
+/// Returns the created rigid body handle.
+fn build_ball(
+  world: &mut PhysicsWorld2D,
+  filter: CollisionFilter,
+) -> RigidBody2D {
+  let ball = RigidBody2DBuilder::new(RigidBodyType::Dynamic)
+    .with_position(0.0, 4.0)
+    .build(world)
+    .unwrap();
+
+  Collider2DBuilder::circle(0.5)
+    .with_collision_filter(filter)
+    .build(world, ball)
+    .unwrap();
+
+  return ball;
+}
+
+/// Allows collisions when both colliders' group and mask settings match.
+#[test]
+fn physics_2d_matching_collision_filters_allow_contact() {
+  let mut world = PhysicsWorld2DBuilder::new().build().unwrap();
+
+  build_ground(
+    &mut world,
+    CollisionFilter {
+      group: 0b0001,
+      mask: 0b0010,
+    },
+  );
+  let ball = build_ball(
+    &mut world,
+    CollisionFilter {
+      group: 0b0010,
+      mask: 0b0001,
+    },
+  );
+
+  step_world(&mut world, DEFAULT_STEP_COUNT);
+
+  let position = ball.position(&world).unwrap();
+
+  assert!(
+    position[1] > -0.25,
+    "ball did not collide with the ground: y={}",
+    position[1],
+  );
+
+  return;
+}
+
+/// Prevents collisions when the colliders' groups and masks do not overlap.
+#[test]
+fn physics_2d_mismatched_collision_filters_prevent_contact() {
+  let mut world = PhysicsWorld2DBuilder::new().build().unwrap();
+
+  build_ground(
+    &mut world,
+    CollisionFilter {
+      group: 0b0001,
+      mask: 0b0001,
+    },
+  );
+  let ball = build_ball(
+    &mut world,
+    CollisionFilter {
+      group: 0b0010,
+      mask: 0b0010,
+    },
+  );
+
+  step_world(&mut world, DEFAULT_STEP_COUNT);
+
+  let position = ball.position(&world).unwrap();
+
+  assert!(
+    position[1] < -5.0,
+    "ball unexpectedly collided with the ground: y={}",
+    position[1],
+  );
+
+  return;
+}

crates/lambda-rs/tests/physics_2d/mod.rs

@@ -4,6 +4,7 @@
 //! surface, including cross-crate wiring through `lambda-rs-platform`.
 
 mod colliders;
+mod collision_filters;
 mod compound_colliders;
 mod materials;