Combine contact events and intersection events into a single event type and flags

CHANGELOG.md

@@ -10,6 +10,10 @@
 - All method referring to `static` rigid-bodies now use `fixed` instead of `static`.
 - Rename `RigidBodyBuilder::new_static, new_kinematic_velocity_based, new_kinematic_velocity_based` to
   `RigidBodyBuilder::fixed, kinematic_velocity_based, kinematic_velocity_based`.
+- The `ContactEvent` and `IntersectionEvent` have been replaced by a single enum `CollisionEvent` in order
+  to simplify the user’s event handling.
+- The `ActiveEvents::CONTACT_EVENTS` and `ActiveEvents::INTERSECTION_EVENTS` flags have been replaced by a single
+  flag `ActiveEvents::COLLISION_EVENTS`.
 
 ## v0.12.0-alpha.0 (2 Jan. 2022)
 ### Fixed

examples2d/ccd2.rs

@@ -33,7 +33,7 @@ pub fn init_world(testbed: &mut Testbed) {
     let collider = ColliderBuilder::cuboid(ground_thickness, ground_size)
         .translation(vector![2.5, 0.0])
         .sensor(true)
-        .active_events(ActiveEvents::INTERSECTION_EVENTS);
+        .active_events(ActiveEvents::COLLISION_EVENTS);
     let sensor_handle = colliders.insert_with_parent(collider, ground_handle, &mut bodies);
 
     /*
@@ -87,8 +87,8 @@ pub fn init_world(testbed: &mut Testbed) {
 
     // Callback that will be executed on the main loop to handle proximities.
     testbed.add_callback(move |mut graphics, physics, events, _| {
-        while let Ok(prox) = events.intersection_events.try_recv() {
+        while let Ok(prox) = events.events.try_recv() {
-            let color = if prox.intersecting {
+            let color = if prox.started() {
                 [1.0, 1.0, 0.0]
             } else {
                 [0.5, 0.5, 1.0]
@@ -96,22 +96,22 @@ pub fn init_world(testbed: &mut Testbed) {
 
             let parent_handle1 = physics
                 .colliders
-                .get(prox.collider1)
+                .get(prox.collider1())
                 .unwrap()
                 .parent()
                 .unwrap();
             let parent_handle2 = physics
                 .colliders
-                .get(prox.collider2)
+                .get(prox.collider2())
                 .unwrap()
                 .parent()
                 .unwrap();
             if let Some(graphics) = &mut graphics {
-                if parent_handle1 != ground_handle && prox.collider1 != sensor_handle {
+                if parent_handle1 != ground_handle && prox.collider1() != sensor_handle {
                     graphics.set_body_color(parent_handle1, color);
                 }
 
-                if parent_handle2 != ground_handle && prox.collider2 != sensor_handle {
+                if parent_handle2 != ground_handle && prox.collider2() != sensor_handle {
                     graphics.set_body_color(parent_handle2, color);
                 }
             }

examples2d/sensor2.rs

@@ -68,15 +68,15 @@ pub fn init_world(testbed: &mut Testbed) {
 
     // Callback that will be executed on the main loop to handle proximities.
     testbed.add_callback(move |mut graphics, physics, events, _| {
-        while let Ok(prox) = events.intersection_events.try_recv() {
+        while let Ok(prox) = events.events.try_recv() {
-            let color = if prox.intersecting {
+            let color = if prox.started() {
                 [1.0, 1.0, 0.0]
             } else {
                 [0.5, 0.5, 1.0]
             };
 
-            let parent_handle1 = physics.colliders[prox.collider1].parent().unwrap();
+            let parent_handle1 = physics.colliders[prox.collider1()].parent().unwrap();
-            let parent_handle2 = physics.colliders[prox.collider2].parent().unwrap();
+            let parent_handle2 = physics.colliders[prox.collider2()].parent().unwrap();
 
             if let Some(graphics) = &mut graphics {
                 if parent_handle1 != ground_handle && parent_handle1 != sensor_handle {

examples3d/ccd3.rs

@@ -92,7 +92,7 @@ pub fn init_world(testbed: &mut Testbed) {
     let collider = ColliderBuilder::ball(1.0)
         .density(10.0)
         .sensor(true)
-        .active_events(ActiveEvents::INTERSECTION_EVENTS);
+        .active_events(ActiveEvents::COLLISION_EVENTS);
     let rigid_body = RigidBodyBuilder::dynamic()
         .linvel(vector![1000.0, 0.0, 0.0])
         .translation(vector![-20.0, shift_y + 2.0, 0.0])
@@ -112,8 +112,8 @@ pub fn init_world(testbed: &mut Testbed) {
 
     // Callback that will be executed on the main loop to handle proximities.
     testbed.add_callback(move |mut graphics, physics, events, _| {
-        while let Ok(prox) = events.intersection_events.try_recv() {
+        while let Ok(prox) = events.events.try_recv() {
-            let color = if prox.intersecting {
+            let color = if prox.started() {
                 [1.0, 1.0, 0.0]
             } else {
                 [0.5, 0.5, 1.0]
@@ -121,13 +121,13 @@ pub fn init_world(testbed: &mut Testbed) {
 
             let parent_handle1 = physics
                 .colliders
-                .get(prox.collider1)
+                .get(prox.collider1())
                 .unwrap()
                 .parent()
                 .unwrap();
             let parent_handle2 = physics
                 .colliders
-                .get(prox.collider2)
+                .get(prox.collider2())
                 .unwrap()
                 .parent()
                 .unwrap();

examples3d/sensor3.rs

@@ -65,22 +65,22 @@ pub fn init_world(testbed: &mut Testbed) {
     let sensor_collider = ColliderBuilder::ball(rad * 5.0)
         .density(0.0)
         .sensor(true)
-        .active_events(ActiveEvents::INTERSECTION_EVENTS);
+        .active_events(ActiveEvents::COLLISION_EVENTS);
     colliders.insert_with_parent(sensor_collider, sensor_handle, &mut bodies);
 
     testbed.set_initial_body_color(sensor_handle, [0.5, 1.0, 1.0]);
 
     // Callback that will be executed on the main loop to handle proximities.
     testbed.add_callback(move |mut graphics, physics, events, _| {
-        while let Ok(prox) = events.intersection_events.try_recv() {
+        while let Ok(prox) = events.events.try_recv() {
-            let color = if prox.intersecting {
+            let color = if prox.started() {
                 [1.0, 1.0, 0.0]
             } else {
                 [0.5, 0.5, 1.0]
             };
 
-            let parent_handle1 = physics.colliders[prox.collider1].parent().unwrap();
+            let parent_handle1 = physics.colliders[prox.collider1()].parent().unwrap();
-            let parent_handle2 = physics.colliders[prox.collider2].parent().unwrap();
+            let parent_handle2 = physics.colliders[prox.collider2()].parent().unwrap();
 
             if let Some(graphics) = &mut graphics {
                 if parent_handle1 != ground_handle && parent_handle1 != sensor_handle {

src/dynamics/ccd/ccd_solver.rs

@@ -5,7 +5,7 @@ use crate::dynamics::{
     RigidBodyCcd, RigidBodyHandle, RigidBodyMassProps, RigidBodyPosition, RigidBodyVelocity,
 };
 use crate::geometry::{
-    ColliderParent, ColliderPosition, ColliderShape, ColliderType, IntersectionEvent, NarrowPhase,
+    ColliderParent, ColliderPosition, ColliderShape, ColliderType, CollisionEvent, NarrowPhase,
 };
 use crate::math::Real;
 use crate::parry::utils::SortedPair;
@@ -613,11 +613,11 @@ impl CCDSolver {
             if !intersect_before
                 && !intersect_after
                 && (co_flags1.active_events | co_flags2.active_events)
-                    .contains(ActiveEvents::INTERSECTION_EVENTS)
+                    .contains(ActiveEvents::COLLISION_EVENTS)
             {
                 // Emit one intersection-started and one intersection-stopped event.
-                events.handle_intersection_event(IntersectionEvent::new(toi.c1, toi.c2, true));
+                events.handle_intersection_event(CollisionEvent::Started(toi.c1, toi.c2));
-                events.handle_intersection_event(IntersectionEvent::new(toi.c1, toi.c2, false));
+                events.handle_intersection_event(CollisionEvent::Stopped(toi.c1, toi.c2));
             }
         }
 

src/geometry/mod.rs

@@ -52,38 +52,44 @@ pub type TOI = parry::query::TOI;
 pub use parry::shape::SharedShape;
 
 #[derive(Copy, Clone, Hash, Debug)]
-/// Events occurring when two collision objects start or stop being in contact (or penetration).
+/// Events occurring when two colliders start or stop being in contact (or intersecting)
-pub enum ContactEvent {
+pub enum CollisionEvent {
-    /// Event occurring when two collision objects start being in contact.
+    /// Event occurring when two colliders start being in contact (or intersecting)
-    ///
-    /// This event is generated whenever the narrow-phase finds a contact between two collision objects that did not have any contact at the last update.
     Started(ColliderHandle, ColliderHandle),
-    /// Event occurring when two collision objects stop being in contact.
+    /// Event occurring when two colliders stop being in contact (or intersecting)
-    ///
-    /// This event is generated whenever the narrow-phase fails to find any contact between two collision objects that did have at least one contact at the last update.
     Stopped(ColliderHandle, ColliderHandle),
 }
 
-#[derive(Copy, Clone, Debug)]
+impl CollisionEvent {
-/// Events occurring when two collision objects start or stop being in close proximity, contact, or disjoint.
+    pub(crate) fn new(h1: ColliderHandle, h2: ColliderHandle, start: bool) -> Self {
-pub struct IntersectionEvent {
+        if start {
-    /// The first collider to which the proximity event applies.
+            Self::Started(h1, h2)
-    pub collider1: ColliderHandle,
+        } else {
-    /// The second collider to which the proximity event applies.
+            Self::Stopped(h1, h2)
-    pub collider2: ColliderHandle,
+        }
-    /// Are the two colliders intersecting?
+    }
-    pub intersecting: bool,
-}
 
-impl IntersectionEvent {
+    /// Is this a `Started` collision event?
-    /// Instantiates a new proximity event.
+    pub fn started(self) -> bool {
-    ///
+        matches!(self, CollisionEvent::Started(_, _))
-    /// Panics if `prev_status` is equal to `new_status`.
+    }
-    pub fn new(collider1: ColliderHandle, collider2: ColliderHandle, intersecting: bool) -> Self {
+
-        Self {
+    /// Is this a `Stopped` collision event?
-            collider1,
+    pub fn stopped(self) -> bool {
-            collider2,
+        matches!(self, CollisionEvent::Stopped(_, _))
-            intersecting,
+    }
+
+    /// The handle of the first collider involved in this collision event.
+    pub fn collider1(self) -> ColliderHandle {
+        match self {
+            Self::Started(h, _) | Self::Stopped(h, _) => h,
+        }
+    }
+
+    /// The handle of the second collider involved in this collision event.
+    pub fn collider2(self) -> ColliderHandle {
+        match self {
+            Self::Started(_, h) | Self::Stopped(_, h) => h,
         }
     }
 }

src/geometry/narrow_phase.rs

@@ -8,9 +8,9 @@ use crate::dynamics::{
 };
 use crate::geometry::{
     BroadPhasePairEvent, ColliderChanges, ColliderGraphIndex, ColliderHandle, ColliderMaterial,
-    ColliderPair, ColliderParent, ColliderPosition, ColliderShape, ColliderType, ContactData,
+    ColliderPair, ColliderParent, ColliderPosition, ColliderShape, ColliderType, CollisionEvent,
-    ContactEvent, ContactManifold, ContactManifoldData, ContactPair, InteractionGraph,
+    ContactData, ContactManifold, ContactManifoldData, ContactPair, InteractionGraph,
-    IntersectionEvent, SolverContact, SolverFlags,
+    SolverContact, SolverFlags,
 };
 use crate::math::{Real, Vector};
 use crate::pipeline::{
@@ -516,10 +516,10 @@ impl NarrowPhase {
                         let co_flag2: &ColliderFlags = colliders.index(pair.collider2.0);
 
                         if (co_flag1.active_events | co_flag2.active_events)
-                            .contains(ActiveEvents::INTERSECTION_EVENTS)
+                            .contains(ActiveEvents::COLLISION_EVENTS)
                         {
                             let prox_event =
-                                IntersectionEvent::new(pair.collider1, pair.collider2, false);
+                                CollisionEvent::Stopped(pair.collider1, pair.collider2);
                             events.handle_intersection_event(prox_event)
                         }
                     }
@@ -551,10 +551,10 @@ impl NarrowPhase {
                             let co_flag2: &ColliderFlags = colliders.index(pair.collider2.0);
 
                             if (co_flag1.active_events | co_flag2.active_events)
-                                .contains(ActiveEvents::CONTACT_EVENTS)
+                                .contains(ActiveEvents::COLLISION_EVENTS)
                             {
                                 events.handle_contact_event(
-                                    ContactEvent::Stopped(pair.collider1, pair.collider2),
+                                    CollisionEvent::Stopped(pair.collider1, pair.collider2),
                                     &ctct,
                                 )
                             }
@@ -795,10 +795,10 @@ impl NarrowPhase {
             let co_flags2: &ColliderFlags = colliders.index(handle2.0);
             let active_events = co_flags1.active_events | co_flags2.active_events;
 
-            if active_events.contains(ActiveEvents::INTERSECTION_EVENTS)
+            if active_events.contains(ActiveEvents::COLLISION_EVENTS)
                 && had_intersection != edge.weight
             {
-                events.handle_intersection_event(IntersectionEvent::new(
+                events.handle_intersection_event(CollisionEvent::new(
                     handle1,
                     handle2,
                     edge.weight,
@@ -1027,15 +1027,15 @@ impl NarrowPhase {
             let active_events = co_flags1.active_events | co_flags2.active_events;
 
             if pair.has_any_active_contact != had_any_active_contact {
-                if active_events.contains(ActiveEvents::CONTACT_EVENTS) {
+                if active_events.contains(ActiveEvents::COLLISION_EVENTS) {
                     if pair.has_any_active_contact {
                         events.handle_contact_event(
-                            ContactEvent::Started(pair.collider1, pair.collider2),
+                            CollisionEvent::Started(pair.collider1, pair.collider2),
                             pair,
                         );
                     } else {
                         events.handle_contact_event(
-                            ContactEvent::Stopped(pair.collider1, pair.collider2),
+                            CollisionEvent::Stopped(pair.collider1, pair.collider2),
                             pair,
                         );
                     }

src/pipeline/event_handler.rs

@@ -1,14 +1,13 @@
-use crate::geometry::{ContactEvent, ContactPair, IntersectionEvent};
+use crate::geometry::{CollisionEvent, ContactPair};
 use crossbeam::channel::Sender;
 
 bitflags::bitflags! {
     #[cfg_attr(feature = "serde-serialize", derive(Serialize, Deserialize))]
     /// Flags affecting the events generated for this collider.
     pub struct ActiveEvents: u32 {
-        /// If set, Rapier will call `EventHandler::handle_intersection_event` whenever relevant for this collider.
+        /// If set, Rapier will call `EventHandler::handle_intersection_event` and
-        const INTERSECTION_EVENTS = 0b0001;
+        /// `EventHandler::handle_contact_event` whenever relevant for this collider.
-        /// If set, Rapier will call `PhysicsHooks::handle_contact_event` whenever relevant for this collider.
+        const COLLISION_EVENTS = 0b0001;
-        const CONTACT_EVENTS = 0b0010;
     }
 }
 
@@ -22,47 +21,40 @@ impl Default for ActiveEvents {
 ///
 /// Implementors of this trait will typically collect these events for future processing.
 pub trait EventHandler: Send + Sync {
-    /// Handle an intersection event.
+    /// Handle a collision event.
     ///
     /// A intersection event is emitted when the state of intersection between two colliders changes.
-    fn handle_intersection_event(&self, event: IntersectionEvent);
+    fn handle_intersection_event(&self, event: CollisionEvent);
     /// Handle a contact event.
     ///
     /// A contact event is emitted when two collider start or stop touching, independently from the
     /// number of contact points involved.
-    fn handle_contact_event(&self, event: ContactEvent, contact_pair: &ContactPair);
+    fn handle_contact_event(&self, event: CollisionEvent, contact_pair: &ContactPair);
 }
 
 impl EventHandler for () {
-    fn handle_intersection_event(&self, _event: IntersectionEvent) {}
+    fn handle_intersection_event(&self, _event: CollisionEvent) {}
-    fn handle_contact_event(&self, _event: ContactEvent, _contact_pair: &ContactPair) {}
+    fn handle_contact_event(&self, _event: CollisionEvent, _contact_pair: &ContactPair) {}
 }
 
-/// A physics event handler that collects events into a crossbeam channel.
+/// A collision event handler that collects events into a crossbeam channel.
 pub struct ChannelEventCollector {
-    intersection_event_sender: Sender<IntersectionEvent>,
+    event_sender: Sender<CollisionEvent>,
-    contact_event_sender: Sender<ContactEvent>,
 }
 
 impl ChannelEventCollector {
-    /// Initialize a new physics event handler from crossbeam channel senders.
+    /// Initialize a new collision event handler from crossbeam channel senders.
-    pub fn new(
+    pub fn new(event_sender: Sender<CollisionEvent>) -> Self {
-        intersection_event_sender: Sender<IntersectionEvent>,
+        Self { event_sender }
-        contact_event_sender: Sender<ContactEvent>,
-    ) -> Self {
-        Self {
-            intersection_event_sender,
-            contact_event_sender,
-        }
     }
 }
 
 impl EventHandler for ChannelEventCollector {
-    fn handle_intersection_event(&self, event: IntersectionEvent) {
+    fn handle_intersection_event(&self, event: CollisionEvent) {
-        let _ = self.intersection_event_sender.send(event);
+        let _ = self.event_sender.send(event);
     }
 
-    fn handle_contact_event(&self, event: ContactEvent, _: &ContactPair) {
+    fn handle_contact_event(&self, event: CollisionEvent, _: &ContactPair) {
-        let _ = self.contact_event_sender.send(event);
+        let _ = self.event_sender.send(event);
     }
 }

src_testbed/harness/mod.rs

@@ -86,12 +86,10 @@ type Callbacks =
 #[allow(dead_code)]
 impl Harness {
     pub fn new_empty() -> Self {
-        let contact_channel = crossbeam::channel::unbounded();
+        let event_channel = crossbeam::channel::unbounded();
-        let proximity_channel = crossbeam::channel::unbounded();
+        let event_handler = ChannelEventCollector::new(event_channel.0);
-        let event_handler = ChannelEventCollector::new(proximity_channel.0, contact_channel.0);
         let events = PhysicsEvents {
-            contact_events: contact_channel.1,
+            events: event_channel.1,
-            intersection_events: proximity_channel.1,
         };
         let physics = PhysicsState::new();
         let state = RunState::new();

src_testbed/physics/mod.rs

@@ -3,7 +3,7 @@ use rapier::dynamics::{
     CCDSolver, ImpulseJointSet, IntegrationParameters, IslandManager, MultibodyJointSet,
     RigidBodySet,
 };
-use rapier::geometry::{BroadPhase, ColliderSet, ContactEvent, IntersectionEvent, NarrowPhase};
+use rapier::geometry::{BroadPhase, ColliderSet, CollisionEvent, NarrowPhase};
 use rapier::math::{Real, Vector};
 use rapier::pipeline::{PhysicsHooks, PhysicsPipeline, QueryPipeline};
 
@@ -107,13 +107,11 @@ impl PhysicsState {
 }
 
 pub struct PhysicsEvents {
-    pub contact_events: Receiver<ContactEvent>,
+    pub events: Receiver<CollisionEvent>,
-    pub intersection_events: Receiver<IntersectionEvent>,
 }
 
 impl PhysicsEvents {
     pub fn poll_all(&self) {
-        while let Ok(_) = self.contact_events.try_recv() {}
+        while let Ok(_) = self.events.try_recv() {}
-        while let Ok(_) = self.intersection_events.try_recv() {}
     }
 }

src_testbed/physx_backend.rs

@@ -213,7 +213,7 @@ impl PhysxWorld {
 
                     rapier2dynamic.insert(rapier_handle, actor);
                 } else {
-                    let actor = physics.create_fixed(pos, ()).unwrap();
+                    let actor = physics.create_static(pos, ()).unwrap();
                     rapier2static.insert(rapier_handle, actor);
                 }
             }
@@ -382,7 +382,7 @@ impl PhysxWorld {
             );
 
             for (_, actor) in rapier2static {
-                scene.add_fixed_actor(actor);
+                scene.add_static_actor(actor);
             }
 
             for (_, actor) in rapier2dynamic {
@@ -712,7 +712,7 @@ type PxPhysicsFoundation = PhysicsFoundation<DefaultAllocator, PxShape>;
 type PxMaterial = physx::material::PxMaterial<()>;
 type PxShape = physx::shape::PxShape<(), PxMaterial>;
 type PxArticulationLink = physx::articulation_link::PxArticulationLink<RigidBodyHandle, PxShape>;
-type PxRigidStatic = physx::rigid_fixed::PxRigidStatic<(), PxShape>;
+type PxRigidStatic = physx::rigid_static::PxRigidStatic<(), PxShape>;
 type PxRigidDynamic = physx::rigid_dynamic::PxRigidDynamic<RigidBodyHandle, PxShape>;
 type PxArticulation = physx::articulation::PxArticulation<(), PxArticulationLink>;
 type PxArticulationReducedCoordinate =