feat(lambda-rs): add 2D colliders

[vmarcella]

Summary

Add 2D collider support on top of the rigid body implementation, including
public builder APIs in lambda-rs, Rapier-backed shape attachment in
lambda-rs-platform, integration coverage, and a demo that exercises material,
density, local transform, and compound-collider behavior.

This PR introduces circle, rectangle, capsule, and convex polygon colliders,
supports attaching multiple colliders to a single rigid body, and verifies
collision response through integration tests and a visual demo.

Related Issues

N/A

Changes

• Add Collider2D, ColliderShape2D, Collider2DBuilder, and collider
  validation/error handling to lambda-rs
• Add Rapier-backed circle, rectangle, capsule, and convex polygon collider
  attachment to lambda-rs-platform
• Support compound colliders by allowing multiple collider attachments per
  rigid body
• Add density, friction, restitution, local offset, and local rotation support
  to collider construction
• Add physics integration test modules for collider shapes, materials, and
  compound-collider behavior
• Add a dedicated physics_colliders_2d demo covering primitives, materials,
  density, local rotation, and compound colliders
• Centralize collider validation in lambda-rs and reduce backend error
  handling to backend-owned failures
• Replace indirect body validation with direct live-handle validation
• Remove the custom Rapier contact hook and encode friction/restitution through
  Rapier combine rules
• Reduce unnecessary per-step backend work by skipping zero-force accumulator
  synchronization

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

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:

cargo +nightly fmt --all
cargo build -p lambda-rs-platform --features physics-2d
cargo build -p lambda-rs --features physics-2d
cargo test -p lambda-rs --features physics-2d collider_2d::tests:: -- --nocapture
cargo test -p lambda-rs-platform --features physics-2d rigid_body_exists_2d_reports_live_slots -- --nocapture
cargo test -p lambda-rs-platform --features physics-2d collider_attachment_mass_plan -- --nocapture
cargo test -p lambda-rs-platform --features physics-2d rapier_friction_encoding_preserves_public_combination_semantics -- --nocapture
cargo test -p lambda-rs --features physics-2d physics_2d_friction_changes_sliding_velocity_decay -- --nocapture
cargo test -p lambda-rs --features physics-2d physics_2d_restitution_changes_bounce_height -- --nocapture
cargo test -p lambda-rs --features physics-2d physics_2d_density_affects_impulse_velocity_delta -- --nocapture
cargo clippy --workspace --all-targets --features physics-2d -- -D warnings

Manual verification steps (if applicable):

1. Run cargo run -p lambda-demos-physics --bin physics_colliders_2d --features physics-2d
2. Verify circle, rectangle, capsule, and convex polygon bodies collide with
   the floor, ramp, walls, and divider
3. Verify friction changes sliding distance, restitution changes bounce, and
   density changes response to the applied impulse

Screenshots/Recordings

Not included in this draft.

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

• Full workspace tests were not run as part of this draft. Two force-lifetime
  tests were previously observed failing independently of the collider
  simplification work and should be evaluated separately before merge.

[Copilot]

Pull request overview

Adds 2D collider support to the existing 2D rigid-body physics surface, including a backend implementation (Rapier), public builder APIs, integration tests, and a demo to exercise the new behavior.

Changes:

• Introduces Collider2D handle types, shape enums, materials, and Collider2DBuilder with validation in lambda-rs.
• Implements Rapier-backed collider attachment (circle/rectangle/capsule/convex polygon) with compound-collider support and material combine semantics in lambda-rs-platform.
• Adds integration tests and a new physics_colliders_2d demo plus accompanying documentation/spec updates.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/specs/physics/colliders-2d.md	New draft spec defining 2D collider API/behavior/validation requirements.
docs/specs/README.md	Adds the colliders spec to the specs index and updates metadata.
demos/physics/src/bin/physics_colliders_2d.rs	New visual/demo app exercising collider shapes, materials, density, offsets/rotation, and compound colliders.
demos/physics/Cargo.toml	Registers the new physics_colliders_2d demo binary under physics-2d.
demos/README.md	Documents physics demos and how to run the new colliders demo.
crates/lambda-rs/tests/integration.rs	Adds a top-level integration test entrypoint and gates physics tests behind physics-2d.
crates/lambda-rs/tests/physics_2d/mod.rs	Adds a physics integration test module root and basic smoke tests.
crates/lambda-rs/tests/physics_2d/colliders.rs	Integration tests for collider shapes and local-rotation behavior.
crates/lambda-rs/tests/physics_2d/materials.rs	Integration tests validating friction/restitution/density effects.
crates/lambda-rs/tests/physics_2d/compound_colliders.rs	Integration tests validating compound colliders affect collision extent.
crates/lambda-rs/src/physics/mod.rs	Wires in and re-exports the new collider module/types.
crates/lambda-rs/src/physics/collider_2d.rs	Implements public collider API, validation, and backend calls.
crates/lambda-rs/src/physics/rigid_body_2d.rs	Adds internal helpers for backend slot access and “live handle” validation.
crates/lambda-rs-platform/src/physics/mod.rs	Re-exports the new backend collider error type.
crates/lambda-rs-platform/src/physics/rapier2d.rs	Adds collider storage/attachment, material combine encoding, and mass-planning for density-driven mass semantics.

---

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

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	74.26%
Lines Covered	13663 / 18399

Changed Files in This PR

File	Coverage	Lines
crates/lambda-rs-platform/src/physics/mod.rs	N/A	(no coverage data)
crates/lambda-rs-platform/src/physics/rapier2d.rs	93.49%	761/814
crates/lambda-rs/src/physics/collider_2d.rs	83.76%	392/468
crates/lambda-rs/src/physics/mod.rs	88.69%	149/168
crates/lambda-rs/src/physics/rigid_body_2d.rs	90.38%	404/447
crates/lambda-rs/tests/integration.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/colliders.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/compound_colliders.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/materials.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/mod.rs	N/A	(no coverage data)

PR Files Coverage: 89.93% (1706/1897 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-03-21 23:18:34 UTC · Commit: e940a4a}