[add] backend raycasting implementation.

Author: vmarcella

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

@@ -9,6 +9,7 @@ pub mod rapier2d;
 pub use rapier2d::{
   Collider2DBackendError,
   PhysicsBackend2D,
+  RaycastHit2DBackend,
   RigidBody2DBackendError,
   RigidBodyType2D,
 };

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

@@ -103,6 +103,21 @@ impl fmt::Display for Collider2DBackendError {
 
 impl Error for Collider2DBackendError {}
 
+/// Backend-agnostic data describing the nearest 2D raycast hit.
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct RaycastHit2DBackend {
+  /// The hit rigid body's slot index.
+  pub body_slot_index: u32,
+  /// The hit rigid body's slot generation.
+  pub body_slot_generation: u32,
+  /// The world-space hit point.
+  pub point: [f32; 2],
+  /// The world-space unit hit normal.
+  pub normal: [f32; 2],
+  /// The non-negative hit distance in meters.
+  pub distance: f32,
+}
+
 /// The fallback mass applied to dynamic bodies before density colliders exist.
 const DYNAMIC_BODY_FALLBACK_MASS_KG: f32 = 1.0;
 
@@ -703,6 +718,82 @@ impl PhysicsBackend2D {
     return body_slots;
   }
 
+  /// Returns the nearest rigid body hit by the provided finite ray segment.
+  ///
+  /// This iterates the live collider set directly instead of using Rapier's
+  /// broad-phase query pipeline. The overlap-query work already established
+  /// that direct iteration is the most reliable way to support read-only
+  /// queries immediately after collider creation, before any simulation step
+  /// has synchronized broad-phase acceleration structures.
+  ///
+  /// # Arguments
+  /// - `origin`: The world-space ray origin.
+  /// - `dir`: The world-space ray direction.
+  /// - `max_dist`: The maximum query distance in meters.
+  ///
+  /// # Returns
+  /// Returns the nearest hit data when any live collider intersects the ray.
+  pub fn raycast_2d(
+    &self,
+    origin: [f32; 2],
+    dir: [f32; 2],
+    max_dist: f32,
+  ) -> Option<RaycastHit2DBackend> {
+    if validate_position(origin[0], origin[1]).is_err()
+      || validate_velocity(dir[0], dir[1]).is_err()
+      || !max_dist.is_finite()
+      || max_dist <= 0.0
+    {
+      return None;
+    }
+
+    let normalized_dir = normalize_query_vector_2d(dir)?;
+    let ray = Ray::new(
+      Vector::new(origin[0], origin[1]),
+      Vector::new(normalized_dir[0], normalized_dir[1]),
+    );
+    let mut nearest_hit = None;
+
+    for (collider_handle, collider) in self.colliders.iter() {
+      // Resolve the public body handle data up front so the final hit payload
+      // stays backend-agnostic and does not expose Rapier collider handles.
+      let Some(body_slot) =
+        self.query_hit_to_parent_body_slot_2d(collider_handle)
+      else {
+        continue;
+      };
+
+      let Some(hit) =
+        cast_live_collider_raycast_hit_2d(collider, &ray, max_dist)
+      else {
+        continue;
+      };
+      let hit_point = ray.point_at(hit.time_of_impact);
+      let candidate = RaycastHit2DBackend {
+        body_slot_index: body_slot.0,
+        body_slot_generation: body_slot.1,
+        point: [hit_point.x, hit_point.y],
+        normal: [hit.normal.x, hit.normal.y],
+        distance: hit.time_of_impact,
+      };
+
+      // The public API only returns the nearest hit, so keep the first minimum
+      // distance we observe while scanning the live collider set.
+      if nearest_hit
+        .as_ref()
+        .is_some_and(|nearest: &RaycastHit2DBackend| {
+          candidate.distance >= nearest.distance
+        })
+      {
+        continue;
+      }
+
+      nearest_hit = Some(candidate);
+    }
+
+    return nearest_hit;
+  }
+
   /// Sets the current position for the referenced body.
   ///
   /// # Arguments
@@ -1477,6 +1568,73 @@ fn validate_velocity(x: f32, y: f32) -> Result<(), RigidBody2DBackendError> {
   return Ok(());
 }
 
+/// Normalizes a finite 2D query vector.
+///
+/// # Arguments
+/// - `vector`: The vector to normalize.
+///
+/// # Returns
+/// Returns the normalized vector when the input has non-zero finite length.
+///
+/// Ray queries normalize directions so Rapier's `time_of_impact` value matches
+/// the world-space travel distance expected by the public API.
+fn normalize_query_vector_2d(vector: [f32; 2]) -> Option<[f32; 2]> {
+  let length = vector[0].hypot(vector[1]);
+
+  if !length.is_finite() || length <= 0.0 {
+    return None;
+  }
+
+  return Some([vector[0] / length, vector[1] / length]);
+}
+
+/// Casts a ray against one live collider and normalizes the reported normal.
+///
+/// When the origin lies inside a collider, Parry may report a zero normal for
+/// the solid hit at distance `0.0`. In that case, this helper performs one
+/// non-solid cast along the same ray to recover a stable outward exit normal
+/// while preserving the `0.0` contact distance expected by the public API.
+///
+/// # Arguments
+/// - `collider`: The live Rapier collider to test.
+/// - `ray`: The normalized query ray.
+/// - `max_dist`: The maximum query distance in meters.
+///
+/// # Returns
+/// Returns normalized hit data when the collider intersects the finite ray.
+fn cast_live_collider_raycast_hit_2d(
+  collider: &Collider,
+  ray: &Ray,
+  max_dist: f32,
+) -> Option<RayIntersection> {
+  // Use a solid cast so callers starting inside geometry receive an immediate
+  // hit at distance `0.0` instead of only the exit point.
+  let mut hit = collider.shape().cast_ray_and_get_normal(
+    collider.position(),
+    ray,
+    max_dist,
+    true,
+  )?;
+
+  let normalized_normal =
+    normalize_query_vector_2d([hit.normal.x, hit.normal.y]).or_else(|| {
+      // Some inside hits report a zero normal. A follow-up non-solid cast
+      // recovers the exit-face normal without changing the public `0.0`
+      // distance contract for origin-inside queries.
+      let exit_hit = collider.shape().cast_ray_and_get_normal(
+        collider.position(),
+        ray,
+        max_dist,
+        false,
+      )?;
+
+      return normalize_query_vector_2d([exit_hit.normal.x, exit_hit.normal.y]);
+    })?;
+
+  hit.normal = Vector::new(normalized_normal[0], normalized_normal[1]);
+  return Some(hit);
+}
+
 /// Validates a 2D force vector.
 ///
 /// # Arguments

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

@@ -13,7 +13,10 @@ use std::{
   },
 };
 
-use lambda_platform::physics::PhysicsBackend2D;
+use lambda_platform::physics::{
+  PhysicsBackend2D,
+  RaycastHit2DBackend,
+};
 
 mod collider_2d;
 mod rigid_body_2d;
@@ -196,13 +199,28 @@ impl PhysicsWorld2D {
   ///
   /// # Returns
   /// Returns the nearest hit, if one exists.
+  ///
+  /// This method preserves an infallible query contract for games: invalid
+  /// inputs return `None` instead of surfacing backend-specific validation
+  /// errors through the high-level API.
   pub fn raycast(
     &self,
-    _origin: [f32; 2],
-    _dir: [f32; 2],
-    _max_dist: f32,
+    origin: [f32; 2],
+    dir: [f32; 2],
+    max_dist: f32,
   ) -> Option<RaycastHit> {
-    return None;
+    if !is_valid_query_point(origin)
+      || !is_valid_query_direction(dir)
+      || !max_dist.is_finite()
+      || max_dist <= 0.0
+    {
+      return None;
+    }
+
+    // The backend performs the geometry query and returns backend-neutral hit
+    // data, which we then bind back to this world's public rigid body handles.
+    let hit = self.backend.raycast_2d(origin, dir, max_dist)?;
+    return Some(self.map_backend_raycast_hit(hit));
   }
 
   /// Rebuilds and deduplicates rigid body handles from backend query hits.
@@ -234,6 +252,26 @@ impl PhysicsWorld2D {
 
     return bodies;
   }
+
+  /// Rebuilds a public raycast hit from backend slot and geometry data.
+  ///
+  /// # Arguments
+  /// - `hit`: The backend hit payload.
+  ///
+  /// # Returns
+  /// Returns a backend-agnostic `RaycastHit`.
+  fn map_backend_raycast_hit(&self, hit: RaycastHit2DBackend) -> RaycastHit {
+    return RaycastHit {
+      body: RigidBody2D::from_backend_slot(
+        self.world_id,
+        hit.body_slot_index,
+        hit.body_slot_generation,
+      ),
+      point: hit.point,
+      normal: hit.normal,
+      distance: hit.distance,
+    };
+  }
 }
 
 /// Builder for `PhysicsWorld2D`.
@@ -409,6 +447,21 @@ fn is_valid_query_point(point: [f32; 2]) -> bool {
   return point[0].is_finite() && point[1].is_finite();
 }
 
+/// Returns whether a ray/query direction has finite non-zero length.
+///
+/// # Arguments
+/// - `direction`: The query direction to validate.
+///
+/// # Returns
+/// Returns `true` when both components are finite and the vector is non-zero.
+fn is_valid_query_direction(direction: [f32; 2]) -> bool {
+  if !direction[0].is_finite() || !direction[1].is_finite() {
+    return false;
+  }
+
+  return direction[0].hypot(direction[1]) > 0.0;
+}
+
 /// Allocates a non-zero unique world identifier.
 fn allocate_world_id() -> u64 {
   loop {

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

@@ -1,12 +1,13 @@
 //! Spatial query integration tests.
 //!
-//! These tests validate point and axis-aligned overlap queries through the
-//! public `lambda-rs` 2D physics API.
+//! These tests validate point queries, overlap queries, and raycasts through
+//! the public `lambda-rs` 2D physics API.
 
 use lambda::physics::{
   Collider2DBuilder,
   PhysicsWorld2D,
   PhysicsWorld2DBuilder,
+  RaycastHit,
   RigidBody2D,
   RigidBody2DBuilder,
   RigidBodyType,
@@ -172,3 +173,92 @@ fn physics_2d_queries_compound_colliders_return_one_body_handle() {
 
   return;
 }
+
+/// Ensures raycasts return the nearest hit body along the segment.
+#[test]
+fn physics_2d_queries_raycast_returns_nearest_hit() {
+  let mut world = PhysicsWorld2DBuilder::new()
+    .with_gravity(0.0, 0.0)
+    .build()
+    .unwrap();
+
+  let near_circle = build_static_circle(&mut world, [2.0, 0.0], 0.5);
+  build_static_rectangle(&mut world, [5.0, 0.0], 0.5, 0.5);
+
+  let hit = world.raycast([0.0, 0.0], [1.0, 0.0], 10.0).unwrap();
+
+  assert_eq!(hit.body, near_circle);
+  assert_eq!(hit.point, [1.5, 0.0]);
+  assert_eq!(hit.distance, 1.5);
+
+  return;
+}
+
+/// Ensures raycast distances are reported in world meters.
+#[test]
+fn physics_2d_queries_raycast_distance_uses_world_units() {
+  let mut world = PhysicsWorld2DBuilder::new()
+    .with_gravity(0.0, 0.0)
+    .build()
+    .unwrap();
+
+  let circle = build_static_circle(&mut world, [5.0, 0.0], 1.0);
+  let hit = world.raycast([0.0, 0.0], [2.0, 0.0], 10.0).unwrap();
+
+  assert_eq!(hit.body, circle);
+  assert_eq!(hit.point, [4.0, 0.0]);
+  assert_eq!(hit.distance, 4.0);
+
+  return;
+}
+
+/// Ensures raycast normals remain unit length.
+#[test]
+fn physics_2d_queries_raycast_returns_unit_normal() {
+  let mut world = PhysicsWorld2DBuilder::new()
+    .with_gravity(0.0, 0.0)
+    .build()
+    .unwrap();
+
+  build_static_circle(&mut world, [4.0, 1.0], 1.0);
+  let hit = world.raycast([0.0, 1.0], [1.0, 0.0], 10.0).unwrap();
+
+  assert_unit_normal(hit);
+
+  return;
+}
+
+/// Ensures solid raycasts report zero distance when starting inside a collider.
+#[test]
+fn physics_2d_queries_raycast_from_inside_reports_zero_distance() {
+  let mut world = PhysicsWorld2DBuilder::new()
+    .with_gravity(0.0, 0.0)
+    .build()
+    .unwrap();
+
+  let rectangle = build_static_rectangle(&mut world, [0.0, 0.0], 1.0, 1.0);
+  let hit = world.raycast([0.0, 0.0], [1.0, 0.0], 10.0).unwrap();
+
+  assert_eq!(hit.body, rectangle);
+  assert_eq!(hit.point, [0.0, 0.0]);
+  assert_eq!(hit.distance, 0.0);
+  assert_unit_normal(hit);
+
+  return;
+}
+
+/// Asserts that a raycast hit normal has unit length within tolerance.
+///
+/// # Arguments
+/// - `hit`: The raycast hit to validate.
+///
+/// # Returns
+/// Returns `()` after validating the hit normal length.
+fn assert_unit_normal(hit: RaycastHit) {
+  let normal_length =
+    (hit.normal[0] * hit.normal[0] + hit.normal[1] * hit.normal[1]).sqrt();
+
+  assert!((normal_length - 1.0).abs() <= 1.0e-5);
+
+  return;
+}