feat(lambda-rs): Add 2d collision events

[vmarcella]

Summary

Add 2D collision queries, collision filtering, and collision start/end events
to the physics-2d feature.

Related Issues

• Resolves [Feature] 2D collision detection and callbacks #121

Changes

• Add public 2D physics API scaffolding in lambda-rs:
  • CollisionEventKind
  • CollisionEvent
  • CollisionFilter
  • RaycastHit
  • PhysicsWorld2D::collision_events()
  • PhysicsWorld2D::query_point()
  • PhysicsWorld2D::query_aabb()
  • PhysicsWorld2D::raycast()
  • Collider2DBuilder::with_collision_filter()
• Add backend support in lambda-rs-platform Rapier integration for:
  • collider collision group/mask filtering
  • point queries
  • AABB overlap queries
  • nearest-hit raycasts
  • body-pair Started collision events
  • body-pair Ended collision events
  • compound-body collider aggregation into one public body-pair event stream
• Add public-to-backend handle mapping support so query and event results can
  be reconstructed as stable RigidBody2D handles
• Add focused integration tests for:
  • collision filters
  • point, AABB, and ray queries
  • collision start events
  • collision end events
  • queue draining behavior
  • compound-body deduplication behavior
• Add a new demo binary:
  • demos/physics/src/bin/physics_collision_events_2d.rs
  • shows floor/ball contact start and end events
  • logs event data and changes ball tint while contact is active
• Add and update documentation:
  • new spec for 2D collision queries and events
  • spec index update
  • docs/features.md update for physics-2d
  • new tutorial for the collision events demo
  • tutorial index update

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/specs, docs/tutorials

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 --features physics-2d
cargo test -p lambda-rs --features physics-2d -- --nocapture
cargo test -p lambda-rs --features physics-2d collision_filters -- --nocapture
cargo test -p lambda-rs --features physics-2d queries -- --nocapture
cargo test -p lambda-rs --features physics-2d collision_events -- --nocapture
cargo build -p lambda-demos-physics --bin physics_collision_events_2d
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Manual verification steps (if applicable):

1. Run cargo run -p lambda-demos-physics --bin physics_collision_events_2d.
2. Observe the ball falling onto the floor and a Started event being logged.
3. Press Space while the ball is grounded to apply the launch impulse.
4. Observe the ball leaving the floor, a corresponding Ended event, and the
   ball tint returning to its non-contact state.

Screenshots/Recordings

Not included. The main visual change is the new
physics_collision_events_2d demo.

Platform Testing

• macOS
• Windows
• Linux

Additional Notes

• Queries intentionally scan the live collider set so they work before the
  first simulation step.
• collision_events() is a post-step drain rather than a callback system,
  which keeps gameplay logic outside backend simulation execution.

[github-actions]

✅ Coverage Report

📊 View Full HTML Report (download artifact)

Overall Coverage

Metric	Value
Total Line Coverage	73.17%
Lines Covered	14121 / 19300

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	92.98%	1047/1126
crates/lambda-rs-platform/src/wgpu/gpu.rs	78.45%	182/232
crates/lambda-rs-platform/src/wgpu/instance.rs	86.67%	78/90
crates/lambda-rs-platform/src/wgpu/pipeline.rs	83.76%	397/474
crates/lambda-rs-platform/src/wgpu/render_pass.rs	84.30%	188/223
crates/lambda-rs-platform/src/wgpu/surface.rs	26.33%	74/281
crates/lambda-rs/src/physics/collider_2d.rs	84.65%	419/495
crates/lambda-rs/src/physics/mod.rs	92.26%	274/297
crates/lambda-rs/src/physics/rigid_body_2d.rs	90.61%	415/458
crates/lambda-rs/src/render/surface.rs	N/A	(no coverage data)
crates/lambda-rs/src/render/targets/surface.rs	42.47%	79/186
crates/lambda-rs/tests/physics_2d/collision_events.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/collision_filters.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/mod.rs	N/A	(no coverage data)
crates/lambda-rs/tests/physics_2d/queries.rs	N/A	(no coverage data)

PR Files Coverage: 81.64% (3153/3862 lines)

---

Generated by cargo-llvm-cov · Latest main coverage

_{Last updated: 2026-04-03 19:19:18 UTC · Commit: 6578f74}

[Copilot]

Pull request overview

Adds 2D collision queries, collision filtering, and post-step collision start/end events to the physics-2d feature, including backend Rapier support plus docs, tests, and a new demo/tutorial to validate and illustrate the intended gameplay-facing workflow.

Changes:

• Extend lambda-rs public 2D physics API with collision events, collision filters, and point/AABB/raycast queries.
• Implement Rapier-backed event aggregation (body-pair scoped), collision group/mask filtering, and live-collider spatial queries in lambda-rs-platform.
• Add integration tests, a new demo binary, and accompanying specs/tutorial documentation.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
docs/tutorials/README.md	Adds the new collision-events tutorial entry and updates index metadata/changelog.
docs/tutorials/physics/basics/collision-events-2d.md	New tutorial describing the collision events demo and usage pattern.
docs/specs/README.md	Adds the collision queries/events spec entry and updates metadata/changelog.
docs/specs/physics/collision-queries-and-events-2d.md	New spec defining 2D collision queries/events/filtering contract.
docs/features.md	Updates physics-2d feature documentation to include queries/events/filtering.
demos/physics/Cargo.toml	Registers the new physics_collision_events_2d demo binary.
demos/physics/src/bin/physics_collision_events_2d.rs	New demo showcasing start/end events and tint changes while in contact.
crates/lambda-rs/tests/physics_2d/mod.rs	Wires new physics-2d test modules (events/filters/queries).
crates/lambda-rs/tests/physics_2d/collision_events.rs	New integration tests for event start/end, queue draining, and compound-body dedup.
crates/lambda-rs/tests/physics_2d/collision_filters.rs	New integration tests validating group/mask collision filtering.
crates/lambda-rs/tests/physics_2d/queries.rs	New integration tests for point/AABB/raycast queries and dedup behavior.
crates/lambda-rs/src/physics/rigid_body_2d.rs	Adds internal constructor for rebuilding public handles from backend slot ids.
crates/lambda-rs/src/physics/mod.rs	Adds public types (CollisionEvent/Kind, CollisionFilter, RaycastHit) and world query/event APIs.
crates/lambda-rs/src/physics/collider_2d.rs	Adds per-collider collision filter configuration and forwards it to the backend.
crates/lambda-rs-platform/src/physics/mod.rs	Re-exports new backend-neutral event/query payload types.
crates/lambda-rs-platform/src/physics/rapier2d.rs	Implements filtering, live-collider queries, and aggregated body-pair collision event collection.

---

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