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

[vmarcella]

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 [Feature] 2D physics world and configuration #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)
• Feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• 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)
• Test (adding or updating tests)
• Build/CI (changes to build process or CI configuration)

Affected Crates

• lambda-rs
• lambda-rs-platform
• lambda-rs-args
• lambda-rs-logging
• 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)
• New code includes appropriate documentation
• Public API changes are documented
• Breaking changes are noted in this PR description

Testing

Commands run:

# 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

• macOS
• Windows
• Linux

Additional Notes

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	45.14%
Lines Covered	5248 / 11627

Changed Files in This PR

File	Coverage	Lines
crates/lambda-rs-platform/src/lib.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/physics/mod.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/physics/rapier2d.rs	93.48%	43/46
crates/lambda-rs-platform/src/wgpu/surface.rs	26.71%	74/277
crates/lambda-rs/src/lib.rs	N/A	(no coverage data)
crates/lambda-rs/src/physics/mod.rs	88.68%	141/159
crates/lambda-rs/src/render/mod.rs	8.42%	58/689
crates/lambda-rs/src/render/window.rs	0.00%	0/63

PR Files Coverage: 25.60% (316/1234 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-02-09 00:51:24 UTC · Commit: e45973b}

[Copilot]

Pull request overview

Adds an opt-in 2D physics world API to lambda-rs (feature-gated), backed by a Rapier-based platform backend, plus a minimal physics demo and accompanying documentation/specs to introduce and validate fixed-timestep stepping.

Changes:

• Introduce lambda::physics::PhysicsWorld2D + builder/validation behind lambda-rs/physics-2d, wired to lambda-rs-platform/physics-2d (Rapier 2D).
• Add a new lambda-demos-physics crate with a physics_falling_quad demo showcasing fixed-timestep stepping and simple kinematic motion.
• Add/extend docs: a 2D physics world spec, a falling-quad tutorial, and feature-flag documentation/index updates.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/tutorials/physics/basics/falling-quad-kinematic.md	New tutorial walking through building the falling-quad demo and fixed-timestep loop.
docs/tutorials/README.md	Adds a Physics tutorial section linking the new tutorial.
docs/specs/physics/physics-world-2d.md	New spec defining the 2D physics world API, validation, stepping semantics, and feature gating.
docs/specs/README.md	Adds a Physics section linking the new 2D physics world spec.
docs/features.md	Documents the new physics-2d feature flags and their crate relationships.
demos/physics/src/lib.rs	New demo crate library stub / crate-level docs.
demos/physics/src/bin/physics_falling_quad.rs	New demo binary implementing fixed-timestep stepping + falling quad rendering.
demos/physics/Cargo.toml	New demos crate config; enables physics-2d by default and exposes validation passthrough features.
crates/lambda-rs/src/physics/mod.rs	New public PhysicsWorld2D API + builder + validation + unit tests (feature-gated via lib.rs).
crates/lambda-rs/src/lib.rs	Exposes pub mod physics behind physics-2d.
crates/lambda-rs/Cargo.toml	Adds physics-2d feature enabling the platform physics backend.
crates/lambda-rs-platform/src/physics/rapier2d.rs	New Rapier-backed internal 2D backend wrapper.
crates/lambda-rs-platform/src/physics/mod.rs	Adds platform physics module and re-export for the backend.
crates/lambda-rs-platform/src/lib.rs	Exposes platform physics module behind physics-2d.
crates/lambda-rs-platform/Cargo.toml	Adds optional rapier2d dependency and physics-2d feature.
Cargo.toml	Adds demos/physics to workspace members (kept out of default-members).
Cargo.lock	Locks new dependency graph additions (Rapier + transitive deps).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Front-matter version is 0.1.3, but the Changelog section only contains an initial v0.1.0 entry. Please add changelog entries up to 0.1.3 (or adjust the front-matter version) to keep spec versioning consistent.

Suggested change

	version: "0.1.3"
	version: "0.1.0"