feat(lambda-rs): Add 2D physics world for managing physics in 2D environments (#176)

## Summary

Add an opt-in 2D physics world API (`PhysicsWorld2D`) to `lambda-rs`,
backed by
Rapier, and provide a minimal demo
and tutorial that render a falling 2D quad while stepping an empty
physics
world.

## Related Issues

- Resolves #118 

## Changes

- Add `lambda::physics::PhysicsWorld2D` and `PhysicsWorld2DBuilder`
behind the
`physics-2d` feature, including validation and fixed-timestep stepping.
- Add `lambda_platform::physics::rapier2d` backend wrapper and wire it
behind
  `lambda-rs-platform/physics-2d`.
- Add unit tests for builder validation and stepping an empty world.
- Add a dedicated physics demos crate (`demos/physics`) and a minimal
falling
quad demo (`physics_falling_quad`) that defaults to `physics-2d`
enabled.
- Add a specification for the 2D physics world under
`docs/specs/physics/`.
- Update `docs/features.md` to document `physics-2d` feature flags and
their
  dependency relationships.
- Add a tutorial documenting how to build the falling quad demo from
scratch.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] Feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation (updates to docs, specs, tutorials, or comments)
- [ ] Refactor (code change that neither fixes a bug nor adds a feature)
- [ ] Performance (change that improves performance)
- [x] Test (adding or updating tests)
- [ ] Build/CI (changes to build process or CI configuration)

## Affected Crates

- [x] `lambda-rs`
- [x] `lambda-rs-platform`
- [ ] `lambda-rs-args`
- [ ] `lambda-rs-logging`
- [x] Other: `demos/physics`, docs

## Checklist

- [ ] Code follows the repository style guidelines (`cargo +nightly fmt
--all`)
- [ ] Code passes clippy (`cargo clippy --workspace --all-targets -- -D
warnings`)
- [ ] Tests pass (`cargo test --workspace`)
- [x] New code includes appropriate documentation
- [x] Public API changes are documented
- [ ] Breaking changes are noted in this PR description

## Testing

**Commands run:**

```bash
# Suggested minimum coverage for this PR:
cargo test -p lambda-rs --features physics-2d

# Demo:
cargo run -p lambda-demos-physics --bin physics_falling_quad
```

**Manual verification steps (if applicable):**

1. Run `cargo run -p lambda-demos-physics --bin physics_falling_quad`.
2. Confirm a 2D quad falls under gravity and remains visible while the
physics
   world steps each fixed tick.

## Screenshots/Recordings

- N/A

## Platform Testing

- [x] macOS
- [ ] Windows
- [ ] Linux

## Additional Notes

Author: vmarcella

Cargo.lock

@@ -11,6 +11,7 @@ members = [
   "tools/lambda_audio",
   # Demo crates (not built by default; see `default-members`).
   "demos/audio",
+  "demos/physics",
   "demos/render",
   "demos/minimal",
 ]

Cargo.toml

@@ -29,6 +29,7 @@ symphonia = { version = "=0.5.5", optional = true, default-features = false, fea
   "wav",
   "pcm",
 ] }
+rapier2d = { version = "=0.32.0", optional = true }
 
 # Force windows crate to 0.62 to unify wgpu-hal and gpu-allocator dependencies.
 # Both crates support this version range, but Cargo may resolve to different
@@ -65,3 +66,8 @@ audio = ["audio-device", "audio-decode-wav", "audio-decode-vorbis"]
 audio-device = ["dep:cpal"]
 audio-decode-wav = ["dep:symphonia"]
 audio-decode-vorbis = ["dep:symphonia"]
+
+# --------------------------------- PHYSICS -----------------------------------
+
+# Umbrella features (disabled by default)
+physics-2d = ["dep:rapier2d"]

crates/lambda-rs-platform/Cargo.toml

@@ -23,3 +23,6 @@ pub mod winit;
   feature = "audio-decode-vorbis"
 ))]
 pub mod audio;
+
+#[cfg(feature = "physics-2d")]
+pub mod physics;

crates/lambda-rs-platform/src/lib.rs

@@ -0,0 +1,9 @@
+//! Internal physics backends.
+//!
+//! This module contains physics backend implementations that support the
+//! higher-level `lambda-rs` physics APIs without exposing vendor types from
+//! `lambda-rs` itself.
+
+pub mod rapier2d;
+
+pub use rapier2d::PhysicsBackend2D;

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

@@ -0,0 +1,110 @@
+//! Rapier-backed 2D physics backend.
+//!
+//! This module provides a minimal wrapper around `rapier2d` to support the
+//! higher-level `lambda-rs` physics APIs without exposing vendor types outside
+//! of the platform layer.
+
+use rapier2d::prelude::*;
+
+/// A 2D physics backend powered by `rapier2d`.
+///
+/// This type is an internal implementation detail used by `lambda-rs`.
+pub struct PhysicsBackend2D {
+  gravity: Vector,
+  integration_parameters: IntegrationParameters,
+  islands: IslandManager,
+  broad_phase: BroadPhaseBvh,
+  narrow_phase: NarrowPhase,
+  bodies: RigidBodySet,
+  colliders: ColliderSet,
+  impulse_joints: ImpulseJointSet,
+  multibody_joints: MultibodyJointSet,
+  ccd_solver: CCDSolver,
+  pipeline: PhysicsPipeline,
+}
+
+impl PhysicsBackend2D {
+  /// Creates a new empty 2D physics backend.
+  ///
+  /// # Arguments
+  /// - `gravity`: The gravity vector in meters per second squared.
+  /// - `timestep_seconds`: The fixed integration timestep in seconds.
+  ///
+  /// # Returns
+  /// Returns a new `PhysicsBackend2D` with no bodies, colliders, or joints.
+  pub fn new(gravity: [f32; 2], timestep_seconds: f32) -> Self {
+    let gravity_vector = Vector::new(gravity[0], gravity[1]);
+
+    let integration_parameters = IntegrationParameters {
+      dt: timestep_seconds,
+      ..Default::default()
+    };
+
+    return Self {
+      gravity: gravity_vector,
+      integration_parameters,
+      islands: IslandManager::new(),
+      broad_phase: BroadPhaseBvh::new(),
+      narrow_phase: NarrowPhase::new(),
+      bodies: RigidBodySet::new(),
+      colliders: ColliderSet::new(),
+      impulse_joints: ImpulseJointSet::new(),
+      multibody_joints: MultibodyJointSet::new(),
+      ccd_solver: CCDSolver::new(),
+      pipeline: PhysicsPipeline::new(),
+    };
+  }
+
+  /// Returns the gravity vector used by this backend.
+  ///
+  /// # Returns
+  /// Returns the gravity vector in meters per second squared.
+  pub fn gravity(&self) -> [f32; 2] {
+    return [self.gravity.x, self.gravity.y];
+  }
+
+  /// Returns the fixed integration timestep in seconds.
+  ///
+  /// # Returns
+  /// Returns the timestep used for each simulation step.
+  pub fn timestep_seconds(&self) -> f32 {
+    return self.integration_parameters.dt;
+  }
+
+  /// Advances the simulation by one fixed timestep.
+  ///
+  /// # Returns
+  /// Returns `()` after applying integration and constraint solving for the
+  /// configured timestep.
+  pub fn step(&mut self) {
+    return self.step_with_timestep_seconds(self.integration_parameters.dt);
+  }
+
+  /// Advances the simulation by the given timestep.
+  ///
+  /// # Arguments
+  /// - `timestep_seconds`: The timestep used for this step.
+  ///
+  /// # Returns
+  /// Returns `()` after applying integration and constraint solving.
+  pub fn step_with_timestep_seconds(&mut self, timestep_seconds: f32) {
+    self.integration_parameters.dt = timestep_seconds;
+
+    self.pipeline.step(
+      self.gravity,
+      &self.integration_parameters,
+      &mut self.islands,
+      &mut self.broad_phase,
+      &mut self.narrow_phase,
+      &mut self.bodies,
+      &mut self.colliders,
+      &mut self.impulse_joints,
+      &mut self.multibody_joints,
+      &mut self.ccd_solver,
+      &(),
+      &(),
+    );
+
+    return;
+  }
+}

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

@@ -89,6 +89,11 @@ render-validation-encoder = []
 render-validation-instancing = []
 render-validation-render-targets = []
 
+# --------------------------------- PHYSICS -----------------------------------
+
+# Umbrella features (disabled by default)
+physics-2d = ["lambda-rs-platform/physics-2d"]
+
 
 # ---------------------------- PLATFORM DEPENDENCIES ---------------------------
 

crates/lambda-rs/Cargo.toml

@@ -29,6 +29,9 @@ pub mod util;
 ))]
 pub mod audio;
 
+#[cfg(feature = "physics-2d")]
+pub mod physics;
+
 /// The logging module provides a simple logging interface for Lambda
 /// applications.
 pub use logging;