From f900cafee417e013e20eeb5e41569344e30828ff Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Wed, 1 Jan 2025 23:40:15 +0200
Subject: [PATCH 1/8] Only store a world-space normal for `ContactManifold`

---
 crates/avian2d/examples/custom_collider.rs    |  5 +-
 .../examples/kinematic_character_2d/plugin.rs | 13 ++---
 .../avian2d/examples/one_way_platform_2d.rs   | 20 +++++---
 .../examples/kinematic_character_3d/plugin.rs | 13 ++---
 src/collision/contact_query.rs                | 39 +++++++--------
 src/collision/mod.rs                          | 47 ++-----------------
 src/debug_render/mod.rs                       | 16 +++++--
 src/dynamics/solver/contact/mod.rs            | 20 +++-----
 8 files changed, 61 insertions(+), 112 deletions(-)

diff --git a/crates/avian2d/examples/custom_collider.rs b/crates/avian2d/examples/custom_collider.rs
index 107d231d..aaaf580c 100644
--- a/crates/avian2d/examples/custom_collider.rs
+++ b/crates/avian2d/examples/custom_collider.rs
@@ -90,15 +90,12 @@ impl AnyCollider for CircleCollider {
 
             vec![ContactManifold {
                 index: 0,
-                normal1,
-                normal2,
+                normal: rotation1 * normal1,
                 contacts: vec![ContactData {
                     feature_id1: PackedFeatureId::face(0),
                     feature_id2: PackedFeatureId::face(0),
                     point1,
                     point2,
-                    normal1,
-                    normal2,
                     penetration: sum_radius - distance_squared.sqrt(),
                     // Impulses are computed by the constraint solver
                     normal_impulse: 0.0,
diff --git a/crates/avian2d/examples/kinematic_character_2d/plugin.rs b/crates/avian2d/examples/kinematic_character_2d/plugin.rs
index 3e4f5c1c..eb5f8d56 100644
--- a/crates/avian2d/examples/kinematic_character_2d/plugin.rs
+++ b/crates/avian2d/examples/kinematic_character_2d/plugin.rs
@@ -269,12 +269,7 @@ fn kinematic_controller_collisions(
     bodies: Query<&RigidBody>,
     collider_parents: Query<&ColliderParent, Without<Sensor>>,
     mut character_controllers: Query<
-        (
-            &mut Position,
-            &Rotation,
-            &mut LinearVelocity,
-            Option<&MaxSlopeAngle>,
-        ),
+        (&mut Position, &mut LinearVelocity, Option<&MaxSlopeAngle>),
         (With<RigidBody>, With<CharacterController>),
     >,
     time: Res<Time>,
@@ -295,7 +290,7 @@ fn kinematic_controller_collisions(
         let character_rb: RigidBody;
         let is_other_dynamic: bool;
 
-        let (mut position, rotation, mut linear_velocity, max_slope_angle) =
+        let (mut position, mut linear_velocity, max_slope_angle) =
             if let Ok(character) = character_controllers.get_mut(collider_parent1.get()) {
                 is_first = true;
                 character_rb = *bodies.get(collider_parent1.get()).unwrap();
@@ -323,9 +318,9 @@ fn kinematic_controller_collisions(
         // Each contact in a single manifold shares the same contact normal.
         for manifold in contacts.manifolds.iter() {
             let normal = if is_first {
-                -manifold.global_normal1(rotation)
+                -manifold.normal
             } else {
-                -manifold.global_normal2(rotation)
+                manifold.normal
             };
 
             let mut deepest_penetration: Scalar = Scalar::MIN;
diff --git a/crates/avian2d/examples/one_way_platform_2d.rs b/crates/avian2d/examples/one_way_platform_2d.rs
index 8b7dc420..314a5d80 100644
--- a/crates/avian2d/examples/one_way_platform_2d.rs
+++ b/crates/avian2d/examples/one_way_platform_2d.rs
@@ -187,7 +187,7 @@ fn pass_through_one_way_platform(
 // It can have read-only access to queries, resources, and other system parameters.
 #[derive(SystemParam)]
 struct PlatformerCollisionHooks<'w, 's> {
-    one_way_platforms_query: Query<'w, 's, Read<OneWayPlatform>>,
+    one_way_platforms_query: Query<'w, 's, (Read<OneWayPlatform>, Read<GlobalTransform>)>,
     // NOTE: This precludes a `OneWayPlatform` passing through a `OneWayPlatform`.
     other_colliders_query: Query<
         'w,
@@ -255,19 +255,24 @@ impl CollisionHooks for PlatformerCollisionHooks<'_, '_> {
 
         // First, figure out which entity is the one-way platform, and which is the other.
         // Choose the appropriate normal for pass-through depending on which is which.
-        let (platform_entity, one_way_platform, other_entity, relevant_normal) =
-            if let Ok(one_way_platform) = self.one_way_platforms_query.get(contacts.entity1) {
+        let (platform_entity, one_way_platform, platform_transform, other_entity, relevant_normal) =
+            if let Ok((one_way_platform, platform_transform)) =
+                self.one_way_platforms_query.get(contacts.entity1)
+            {
                 (
                     contacts.entity1,
                     one_way_platform,
+                    platform_transform,
                     contacts.entity2,
                     RelevantNormal::Normal1,
                 )
-            } else if let Ok(one_way_platform) = self.one_way_platforms_query.get(contacts.entity2)
+            } else if let Ok((one_way_platform, platform_transform)) =
+                self.one_way_platforms_query.get(contacts.entity2)
             {
                 (
                     contacts.entity2,
                     one_way_platform,
+                    platform_transform,
                     contacts.entity1,
                     RelevantNormal::Normal2,
                 )
@@ -314,13 +319,14 @@ impl CollisionHooks for PlatformerCollisionHooks<'_, '_> {
             Err(_) | Ok(None) | Ok(Some(PassThroughOneWayPlatform::ByNormal)) => {
                 // If all contact normals are in line with the local up vector of this platform,
                 // then this collision should occur: the entity is on top of the platform.
+                let platform_up = platform_transform.up().truncate().adjust_precision();
                 if contacts.manifolds.iter().all(|manifold| {
                     let normal = match relevant_normal {
-                        RelevantNormal::Normal1 => manifold.normal1,
-                        RelevantNormal::Normal2 => manifold.normal2,
+                        RelevantNormal::Normal1 => manifold.normal,
+                        RelevantNormal::Normal2 => -manifold.normal,
                     };
 
-                    normal.length() > Scalar::EPSILON && normal.dot(Vector::Y) >= 0.5
+                    normal.length() > Scalar::EPSILON && normal.dot(platform_up) >= 0.5
                 }) {
                     true
                 } else {
diff --git a/crates/avian3d/examples/kinematic_character_3d/plugin.rs b/crates/avian3d/examples/kinematic_character_3d/plugin.rs
index 41f32268..8349f0a5 100644
--- a/crates/avian3d/examples/kinematic_character_3d/plugin.rs
+++ b/crates/avian3d/examples/kinematic_character_3d/plugin.rs
@@ -285,12 +285,7 @@ fn kinematic_controller_collisions(
     bodies: Query<&RigidBody>,
     collider_parents: Query<&ColliderParent, Without<Sensor>>,
     mut character_controllers: Query<
-        (
-            &mut Position,
-            &Rotation,
-            &mut LinearVelocity,
-            Option<&MaxSlopeAngle>,
-        ),
+        (&mut Position, &mut LinearVelocity, Option<&MaxSlopeAngle>),
         (With<RigidBody>, With<CharacterController>),
     >,
     time: Res<Time>,
@@ -311,7 +306,7 @@ fn kinematic_controller_collisions(
         let character_rb: RigidBody;
         let is_other_dynamic: bool;
 
-        let (mut position, rotation, mut linear_velocity, max_slope_angle) =
+        let (mut position, mut linear_velocity, max_slope_angle) =
             if let Ok(character) = character_controllers.get_mut(collider_parent1.get()) {
                 is_first = true;
                 character_rb = *bodies.get(collider_parent1.get()).unwrap();
@@ -339,9 +334,9 @@ fn kinematic_controller_collisions(
         // Each contact in a single manifold shares the same contact normal.
         for manifold in contacts.manifolds.iter() {
             let normal = if is_first {
-                -manifold.global_normal1(rotation)
+                -manifold.normal
             } else {
-                -manifold.global_normal2(rotation)
+                manifold.normal
             };
 
             let mut deepest_penetration: Scalar = Scalar::MIN;
diff --git a/src/collision/contact_query.rs b/src/collision/contact_query.rs
index cd59d0f0..c7e59ec8 100644
--- a/src/collision/contact_query.rs
+++ b/src/collision/contact_query.rs
@@ -90,7 +90,7 @@ pub fn contact(
             let normal1: Vector = (rotation1.inverse() * Vector::from(contact.normal1)).normalize();
             let normal2: Vector = (rotation2.inverse() * Vector::from(contact.normal2)).normalize();
 
-            // Make sure normals are valid
+            // Make sure the normal is valid
             if !normal1.is_normalized() || !normal2.is_normalized() {
                 return None;
             }
@@ -156,8 +156,12 @@ pub fn contact_manifolds(
     rotation2: impl Into<Rotation>,
     prediction_distance: Scalar,
 ) -> Vec<ContactManifold> {
-    let isometry1 = make_isometry(position1.into(), rotation1.into());
-    let isometry2 = make_isometry(position2.into(), rotation2.into());
+    let position1: Position = position1.into();
+    let position2: Position = position2.into();
+    let rotation1: Rotation = rotation1.into();
+    let rotation2: Rotation = rotation2.into();
+    let isometry1 = make_isometry(position1, rotation1);
+    let isometry2 = make_isometry(position2, rotation2);
     let isometry12 = isometry1.inv_mul(&isometry2);
 
     // TODO: Reuse manifolds from previous frame to improve performance
@@ -184,22 +188,18 @@ pub fn contact_manifolds(
                 shape2,
                 prediction_distance,
             ) {
-                let normal1 = Vector::from(contact.normal1);
-                let normal2 = Vector::from(contact.normal2);
+                let normal = rotation1 * Vector::from(contact.normal1);
 
-                // Make sure normals are valid
-                if !normal1.is_normalized() || !normal2.is_normalized() {
+                // Make sure the normal is valid
+                if !normal.is_normalized() {
                     return vec![];
                 }
 
                 return vec![ContactManifold {
-                    normal1,
-                    normal2,
+                    normal,
                     contacts: vec![ContactData::new(
                         contact.point1.into(),
                         contact.point2.into(),
-                        normal1,
-                        normal2,
                         -contact.dist,
                     )],
                     index: 0,
@@ -215,25 +215,20 @@ pub fn contact_manifolds(
         .filter_map(|manifold| {
             let subpos1 = manifold.subshape_pos1.unwrap_or_default();
             let subpos2 = manifold.subshape_pos2.unwrap_or_default();
-            let normal1: Vector = subpos1
+            let local_normal: Vector = subpos1
                 .rotation
                 .transform_vector(&manifold.local_n1)
                 .normalize()
                 .into();
-            let normal2: Vector = subpos2
-                .rotation
-                .transform_vector(&manifold.local_n2)
-                .normalize()
-                .into();
+            let normal = rotation1 * local_normal;
 
-            // Make sure normals are valid
-            if !normal1.is_normalized() || !normal2.is_normalized() {
+            // Make sure the normal is valid
+            if !normal.is_normalized() {
                 return None;
             }
 
             let manifold = ContactManifold {
-                normal1,
-                normal2,
+                normal,
                 contacts: manifold
                     .contacts()
                     .iter()
@@ -241,8 +236,6 @@ pub fn contact_manifolds(
                         ContactData::new(
                             subpos1.transform_point(&contact.local_p1).into(),
                             subpos2.transform_point(&contact.local_p2).into(),
-                            normal1,
-                            normal2,
                             -contact.dist,
                         )
                         .with_feature_ids(contact.fid1.into(), contact.fid2.into())
diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index b5d8ae47..a808619a 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -342,27 +342,15 @@ impl Contacts {
 pub struct ContactManifold {
     /// The contacts in this manifold.
     pub contacts: Vec<ContactData>,
-    /// A contact normal shared by all contacts in this manifold,
-    /// expressed in the local space of the first entity.
-    pub normal1: Vector,
-    /// A contact normal shared by all contacts in this manifold,
-    /// expressed in the local space of the second entity.
-    pub normal2: Vector,
+    /// The unit contact normal in world space, pointing from the first entity to the second.
+    ///
+    /// The same normal is shared by all contact points in this manifold,
+    pub normal: Vector,
     /// The index of the manifold in the collision.
     pub index: usize,
 }
 
 impl ContactManifold {
-    /// Returns the world-space contact normal pointing towards the exterior of the first entity.
-    pub fn global_normal1(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal1
-    }
-
-    /// Returns the world-space contact normal pointing towards the exterior of the second entity.
-    pub fn global_normal2(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal2
-    }
-
     /// Copies impulses from previous contacts to matching contacts in `self`.
     ///
     /// Contacts are first matched based on their [feature IDs](PackedFeatureId), and if they are unknown,
@@ -514,10 +502,6 @@ pub struct ContactData {
     pub point1: Vector,
     /// Contact point on the second entity in local coordinates.
     pub point2: Vector,
-    /// A contact normal expressed in the local space of the first entity.
-    pub normal1: Vector,
-    /// A contact normal expressed in the local space of the second entity.
-    pub normal2: Vector,
     /// Penetration depth.
     pub penetration: Scalar,
     /// The impulse applied to the first body along the normal.
@@ -549,18 +533,10 @@ impl ContactData {
     ///
     /// [Feature IDs](PackedFeatureId) can be specified for the contact points using [`with_feature_ids`](Self::with_feature_ids).
     #[allow(clippy::too_many_arguments)]
-    pub fn new(
-        point1: Vector,
-        point2: Vector,
-        normal1: Vector,
-        normal2: Vector,
-        penetration: Scalar,
-    ) -> Self {
+    pub fn new(point1: Vector, point2: Vector, penetration: Scalar) -> Self {
         Self {
             point1,
             point2,
-            normal1,
-            normal2,
             penetration,
             normal_impulse: 0.0,
             tangent_impulse: default(),
@@ -616,21 +592,10 @@ impl ContactData {
         position.0 + rotation * self.point2
     }
 
-    /// Returns the world-space contact normal pointing towards the exterior of the first entity.
-    pub fn global_normal1(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal1
-    }
-
-    /// Returns the world-space contact normal pointing towards the exterior of the second entity.
-    pub fn global_normal2(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal2
-    }
-
     /// Flips the contact data, swapping the points, normals, and feature IDs,
     /// and negating the impulses.
     pub fn flip(&mut self) {
         std::mem::swap(&mut self.point1, &mut self.point2);
-        std::mem::swap(&mut self.normal1, &mut self.normal2);
         std::mem::swap(&mut self.feature_id1, &mut self.feature_id2);
         self.normal_impulse = -self.normal_impulse;
         self.tangent_impulse = -self.tangent_impulse;
@@ -642,8 +607,6 @@ impl ContactData {
         Self {
             point1: self.point2,
             point2: self.point1,
-            normal1: self.normal2,
-            normal2: self.normal1,
             penetration: self.penetration,
             normal_impulse: -self.normal_impulse,
             tangent_impulse: -self.tangent_impulse,
diff --git a/src/debug_render/mod.rs b/src/debug_render/mod.rs
index 70435ce9..7e73673d 100644
--- a/src/debug_render/mod.rs
+++ b/src/debug_render/mod.rs
@@ -319,8 +319,6 @@ fn debug_render_contacts(
             for contact in manifold.contacts.iter() {
                 let p1 = contact.global_point1(position1, rotation1);
                 let p2 = contact.global_point2(position2, rotation2);
-                let normal1 = contact.global_normal1(rotation1);
-                let normal2 = contact.global_normal2(rotation2);
 
                 // Don't render contacts that aren't penetrating
                 if contact.penetration <= Scalar::EPSILON {
@@ -356,8 +354,18 @@ fn debug_render_contacts(
                             }
                         };
 
-                    gizmos.draw_arrow(p1, p1 + normal1 * length, 0.1 * length_unit.0, color);
-                    gizmos.draw_arrow(p2, p2 + normal2 * length, 0.1 * length_unit.0, color_dim);
+                    gizmos.draw_arrow(
+                        p1,
+                        p1 + manifold.normal * length,
+                        0.1 * length_unit.0,
+                        color,
+                    );
+                    gizmos.draw_arrow(
+                        p2,
+                        p2 - manifold.normal * length,
+                        0.1 * length_unit.0,
+                        color_dim,
+                    );
                 }
             }
         }
diff --git a/src/dynamics/solver/contact/mod.rs b/src/dynamics/solver/contact/mod.rs
index 6a818bb1..507f1c45 100644
--- a/src/dynamics/solver/contact/mod.rs
+++ b/src/dynamics/solver/contact/mod.rs
@@ -102,15 +102,6 @@ impl ContactConstraint {
         let collision_margin: Scalar = collision_margin.into().0;
         let speculative_margin: Scalar = speculative_margin.into().0;
 
-        // Local-space outward contact normal on the first body.
-        // The normal is transformed from collider-space to body-space.
-        let local_normal1 = collider_transform1.map_or(manifold.normal1, |transform| {
-            transform.rotation * manifold.normal1
-        });
-
-        // The world-space normal used for the contact solve.
-        let normal = *body1.rotation * local_normal1;
-
         // TODO: Cache these?
         // TODO: How should we properly take the locked axes into account for the mass here?
         let inverse_mass_sum = body1.mass().inverse() + body2.mass().inverse();
@@ -124,7 +115,7 @@ impl ContactConstraint {
             collider_entity2,
             friction,
             restitution,
-            normal,
+            normal: manifold.normal,
             points: Vec::with_capacity(manifold.contacts.len()),
             manifold_index: manifold_id,
         };
@@ -158,8 +149,9 @@ impl ContactConstraint {
 
             // Keep the contact if (1) the separation distance is below the required threshold,
             // or if (2) the bodies are expected to come into contact within the next frame.
+            let normal_speed = relative_velocity.dot(constraint.normal);
             let keep_contact = effective_distance < speculative_margin || {
-                let delta_distance = relative_velocity.dot(normal) * delta_secs;
+                let delta_distance = normal_speed * delta_secs;
                 effective_distance + delta_distance < speculative_margin
             };
 
@@ -175,7 +167,7 @@ impl ContactConstraint {
                     i2,
                     r1,
                     r2,
-                    normal,
+                    constraint.normal,
                     warm_start.then_some(contact.normal_impulse),
                     softness,
                 ),
@@ -196,8 +188,8 @@ impl ContactConstraint {
                 local_anchor2,
                 anchor1: r1,
                 anchor2: r2,
-                normal_speed: normal.dot(relative_velocity),
-                initial_separation: -contact.penetration - (r2 - r1).dot(normal),
+                normal_speed,
+                initial_separation: -contact.penetration - (r2 - r1).dot(constraint.normal),
             };
 
             constraint.points.push(point);

From aa178834746c61fcbad7b4d2e59a61dc55dd5c80 Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Wed, 1 Jan 2025 23:54:17 +0200
Subject: [PATCH 2/8] Use `ArrayVec` for 2D contact points in `ContactManifold`

---
 crates/avian2d/Cargo.toml                  |  1 +
 crates/avian2d/examples/custom_collider.rs | 10 +++++-----
 crates/avian3d/Cargo.toml                  |  1 +
 src/collision/contact_query.rs             |  7 +++++++
 src/collision/mod.rs                       |  6 +++++-
 src/lib.rs                                 |  8 ++++++++
 6 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/crates/avian2d/Cargo.toml b/crates/avian2d/Cargo.toml
index e82e0803..7cefeb41 100644
--- a/crates/avian2d/Cargo.toml
+++ b/crates/avian2d/Cargo.toml
@@ -73,6 +73,7 @@ nalgebra = { version = "0.33", features = ["convert-glam029"], optional = true }
 serde = { version = "1", features = ["derive"], optional = true }
 derive_more = "1"
 indexmap = "2.0.0"
+arrayvec = "0.7"
 fxhash = "0.2.1"
 itertools = "0.13"
 bitflags = "2.5.0"
diff --git a/crates/avian2d/examples/custom_collider.rs b/crates/avian2d/examples/custom_collider.rs
index aaaf580c..500a7353 100644
--- a/crates/avian2d/examples/custom_collider.rs
+++ b/crates/avian2d/examples/custom_collider.rs
@@ -91,16 +91,16 @@ impl AnyCollider for CircleCollider {
             vec![ContactManifold {
                 index: 0,
                 normal: rotation1 * normal1,
-                contacts: vec![ContactData {
-                    feature_id1: PackedFeatureId::face(0),
-                    feature_id2: PackedFeatureId::face(0),
+                contacts: avian2d::data_structures::ArrayVec::from_iter([ContactData {
                     point1,
                     point2,
                     penetration: sum_radius - distance_squared.sqrt(),
-                    // Impulses are computed by the constraint solver
+                    // Impulses are computed by the constraint solver.
                     normal_impulse: 0.0,
                     tangent_impulse: 0.0,
-                }],
+                    feature_id1: PackedFeatureId::face(0),
+                    feature_id2: PackedFeatureId::face(0),
+                }]),
             }]
         } else {
             vec![]
diff --git a/crates/avian3d/Cargo.toml b/crates/avian3d/Cargo.toml
index 3685afa2..e639203a 100644
--- a/crates/avian3d/Cargo.toml
+++ b/crates/avian3d/Cargo.toml
@@ -75,6 +75,7 @@ nalgebra = { version = "0.33", features = ["convert-glam029"], optional = true }
 serde = { version = "1", features = ["derive"], optional = true }
 derive_more = "1"
 indexmap = "2.0.0"
+arrayvec = "0.7"
 fxhash = "0.2.1"
 itertools = "0.13"
 bitflags = "2.5.0"
diff --git a/src/collision/contact_query.rs b/src/collision/contact_query.rs
index c7e59ec8..f54759ae 100644
--- a/src/collision/contact_query.rs
+++ b/src/collision/contact_query.rs
@@ -197,6 +197,13 @@ pub fn contact_manifolds(
 
                 return vec![ContactManifold {
                     normal,
+                    #[cfg(feature = "2d")]
+                    contacts: arrayvec::ArrayVec::from_iter([ContactData::new(
+                        contact.point1.into(),
+                        contact.point2.into(),
+                        -contact.dist,
+                    )]),
+                    #[cfg(feature = "3d")]
                     contacts: vec![ContactData::new(
                         contact.point1.into(),
                         contact.point2.into(),
diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index a808619a..45c60946 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -340,7 +340,11 @@ impl Contacts {
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct ContactManifold {
-    /// The contacts in this manifold.
+    /// The contact points in this manifold.
+    #[cfg(feature = "2d")]
+    pub contacts: arrayvec::ArrayVec<ContactData, 2>,
+    /// The contact points in this manifold.
+    #[cfg(feature = "3d")]
     pub contacts: Vec<ContactData>,
     /// The unit contact normal in world space, pointing from the first entity to the second.
     ///
diff --git a/src/lib.rs b/src/lib.rs
index 47171b0c..b767d453 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -490,6 +490,14 @@ pub mod schedule;
 pub mod spatial_query;
 pub mod sync;
 
+// TODO: Make this a proper module once we have more data structures, like an `UnGraph`.
+#[cfg(feature = "2d")]
+pub mod data_structures {
+    //! Special data structures used in Avian.
+
+    pub use arrayvec::ArrayVec;
+}
+
 mod type_registration;
 pub use type_registration::PhysicsTypeRegistrationPlugin;
 

From 708d79d0dc333dbc3f5a9454f6848908ada020b8 Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Thu, 2 Jan 2025 00:16:48 +0200
Subject: [PATCH 3/8] Rename `ContactData` to `ContactPoint` and `contacts` to
 `points`

---
 crates/avian2d/examples/custom_collider.rs    |  2 +-
 .../examples/kinematic_character_2d/plugin.rs |  2 +-
 .../avian2d/examples/one_way_platform_2d.rs   |  2 +-
 .../examples/kinematic_character_3d/plugin.rs |  2 +-
 src/collision/contact_query.rs                |  8 +--
 src/collision/mod.rs                          | 64 ++++++++++++-------
 src/collision/narrow_phase.rs                 |  4 +-
 src/debug_render/mod.rs                       |  2 +-
 src/dynamics/solver/contact/mod.rs            |  4 +-
 src/dynamics/solver/mod.rs                    |  3 +-
 10 files changed, 54 insertions(+), 39 deletions(-)

diff --git a/crates/avian2d/examples/custom_collider.rs b/crates/avian2d/examples/custom_collider.rs
index 500a7353..a412d97e 100644
--- a/crates/avian2d/examples/custom_collider.rs
+++ b/crates/avian2d/examples/custom_collider.rs
@@ -91,7 +91,7 @@ impl AnyCollider for CircleCollider {
             vec![ContactManifold {
                 index: 0,
                 normal: rotation1 * normal1,
-                contacts: avian2d::data_structures::ArrayVec::from_iter([ContactData {
+                points: avian2d::data_structures::ArrayVec::from_iter([ContactPoint {
                     point1,
                     point2,
                     penetration: sum_radius - distance_squared.sqrt(),
diff --git a/crates/avian2d/examples/kinematic_character_2d/plugin.rs b/crates/avian2d/examples/kinematic_character_2d/plugin.rs
index eb5f8d56..3c981327 100644
--- a/crates/avian2d/examples/kinematic_character_2d/plugin.rs
+++ b/crates/avian2d/examples/kinematic_character_2d/plugin.rs
@@ -326,7 +326,7 @@ fn kinematic_controller_collisions(
             let mut deepest_penetration: Scalar = Scalar::MIN;
 
             // Solve each penetrating contact in the manifold.
-            for contact in manifold.contacts.iter() {
+            for contact in manifold.points.iter() {
                 if contact.penetration > 0.0 {
                     position.0 += normal * contact.penetration;
                 }
diff --git a/crates/avian2d/examples/one_way_platform_2d.rs b/crates/avian2d/examples/one_way_platform_2d.rs
index 314a5d80..2e2e26ad 100644
--- a/crates/avian2d/examples/one_way_platform_2d.rs
+++ b/crates/avian2d/examples/one_way_platform_2d.rs
@@ -285,7 +285,7 @@ impl CollisionHooks for PlatformerCollisionHooks<'_, '_> {
         if one_way_platform.0.contains(&other_entity) {
             let any_penetrating = contacts.manifolds.iter().any(|manifold| {
                 manifold
-                    .contacts
+                    .points
                     .iter()
                     .any(|contact| contact.penetration > 0.0)
             });
diff --git a/crates/avian3d/examples/kinematic_character_3d/plugin.rs b/crates/avian3d/examples/kinematic_character_3d/plugin.rs
index 8349f0a5..545202fd 100644
--- a/crates/avian3d/examples/kinematic_character_3d/plugin.rs
+++ b/crates/avian3d/examples/kinematic_character_3d/plugin.rs
@@ -342,7 +342,7 @@ fn kinematic_controller_collisions(
             let mut deepest_penetration: Scalar = Scalar::MIN;
 
             // Solve each penetrating contact in the manifold.
-            for contact in manifold.contacts.iter() {
+            for contact in manifold.points.iter() {
                 if contact.penetration > 0.0 {
                     position.0 += normal * contact.penetration;
                 }
diff --git a/src/collision/contact_query.rs b/src/collision/contact_query.rs
index f54759ae..d30fc14c 100644
--- a/src/collision/contact_query.rs
+++ b/src/collision/contact_query.rs
@@ -198,13 +198,13 @@ pub fn contact_manifolds(
                 return vec![ContactManifold {
                     normal,
                     #[cfg(feature = "2d")]
-                    contacts: arrayvec::ArrayVec::from_iter([ContactData::new(
+                    points: arrayvec::ArrayVec::from_iter([ContactPoint::new(
                         contact.point1.into(),
                         contact.point2.into(),
                         -contact.dist,
                     )]),
                     #[cfg(feature = "3d")]
-                    contacts: vec![ContactData::new(
+                    points: vec![ContactPoint::new(
                         contact.point1.into(),
                         contact.point2.into(),
                         -contact.dist,
@@ -236,11 +236,11 @@ pub fn contact_manifolds(
 
             let manifold = ContactManifold {
                 normal,
-                contacts: manifold
+                points: manifold
                     .contacts()
                     .iter()
                     .map(|contact| {
-                        ContactData::new(
+                        ContactPoint::new(
                             subpos1.transform_point(&contact.local_p1).into(),
                             subpos2.transform_point(&contact.local_p2).into(),
                             -contact.dist,
diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index 45c60946..fd14e262 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -323,7 +323,7 @@ impl Contacts {
     /// the penetration depth will be negative.
     ///
     /// If there are no contacts, `None` is returned.
-    pub fn find_deepest_contact(&self) -> Option<&ContactData> {
+    pub fn find_deepest_contact(&self) -> Option<&ContactPoint> {
         self.manifolds
             .iter()
             .filter_map(|manifold| manifold.find_deepest_contact())
@@ -335,20 +335,32 @@ impl Contacts {
     }
 }
 
-/// A contact manifold between two colliders, containing a set of contact points.
-/// Each contact in a manifold shares the same contact normal.
+/// A contact manifold describing a contact surface between two colliders,
+/// represented by a set of [contact points](ContactPoint) and surface properties.
+///
+/// A manifold can typically be a single point, a line segment, or a polygon formed by its contact points.
+/// Each contact point in a manifold shares the same contact normal.
+#[cfg_attr(
+    feature = "2d",
+    doc = "
+In 2D, contact manifolds are limited to 2 points."
+)]
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct ContactManifold {
-    /// The contact points in this manifold.
+    /// The contact points in this manifold. Limited to 2 points in 2D.
+    ///
+    /// Each point in a manifold shares the same `normal`.
     #[cfg(feature = "2d")]
-    pub contacts: arrayvec::ArrayVec<ContactData, 2>,
+    pub points: arrayvec::ArrayVec<ContactPoint, 2>,
     /// The contact points in this manifold.
+    ///
+    /// Each point in a manifold shares the same `normal`.
     #[cfg(feature = "3d")]
-    pub contacts: Vec<ContactData>,
-    /// The unit contact normal in world space, pointing from the first entity to the second.
+    pub points: Vec<ContactPoint>,
+    /// The unit contact normal in world space, pointing from the first shape to the second.
     ///
-    /// The same normal is shared by all contact points in this manifold,
+    /// The same normal is shared by all `points` in a manifold,
     pub normal: Vector,
     /// The index of the manifold in the collision.
     pub index: usize,
@@ -362,13 +374,13 @@ impl ContactManifold {
     /// for determining if points are too far away from each other to be considered matching.
     pub fn match_contacts(
         &mut self,
-        previous_contacts: &[ContactData],
+        previous_contacts: &[ContactPoint],
         distance_threshold: Scalar,
     ) {
         // The squared maximum distance for two contact points to be considered matching.
         let distance_threshold_squared = distance_threshold.powi(2);
 
-        for contact in self.contacts.iter_mut() {
+        for contact in self.points.iter_mut() {
             for previous_contact in previous_contacts.iter() {
                 // If the feature IDs match, copy the contact impulses over for warm starting.
                 if (contact.feature_id1 == previous_contact.feature_id1
@@ -406,14 +418,14 @@ impl ContactManifold {
         }
     }
 
-    /// Returns the contact with the largest penetration depth.
+    /// Returns the contact point with the largest penetration depth.
     ///
     /// If the objects are separated but there is still a speculative contact,
     /// the penetration depth will be negative.
     ///
     /// If there are no contacts, `None` is returned.
-    pub fn find_deepest_contact(&self) -> Option<&ContactData> {
-        self.contacts.iter().max_by(|a, b| {
+    pub fn find_deepest_contact(&self) -> Option<&ContactPoint> {
+        self.points.iter().max_by(|a, b| {
             a.penetration
                 .partial_cmp(&b.penetration)
                 .unwrap_or(std::cmp::Ordering::Equal)
@@ -424,7 +436,7 @@ impl ContactManifold {
 /// Data related to a single contact between two bodies.
 ///
 /// If you want a contact that belongs to a [contact manifold](ContactManifold) and has more data,
-/// see [`ContactData`].
+/// see [`ContactPoint`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct SingleContact {
@@ -498,27 +510,31 @@ impl SingleContact {
     }
 }
 
-/// Data related to a contact between two bodies.
+/// Data associated with a contact point in a [`ContactManifold`].
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
-pub struct ContactData {
+pub struct ContactPoint {
     /// Contact point on the first entity in local coordinates.
     pub point1: Vector,
     /// Contact point on the second entity in local coordinates.
     pub point2: Vector,
-    /// Penetration depth.
+    /// The penetration depth.
+    ///
+    /// Can be negative if the objects are separated and [speculative collision] is enabled.
+    ///
+    /// [speculative collision]: crate::dynamics::ccd#speculative-collision
     pub penetration: Scalar,
-    /// The impulse applied to the first body along the normal.
+    /// The impulse applied to the first body along the contact normal.
     ///
     /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
     pub normal_impulse: Scalar,
-    /// The impulse applied to the first body along the tangent. This corresponds to the impulse caused by friction.
+    /// The impulse applied to the first body along the contact tangent. This corresponds to the impulse caused by friction.
     ///
     /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
     #[cfg(feature = "2d")]
     #[doc(alias = "friction_impulse")]
     pub tangent_impulse: Scalar,
-    /// The impulse applied to the first body along the tangent. This corresponds to the impulse caused by friction.
+    /// The impulse applied to the first body along the contact tangent. This corresponds to the impulse caused by friction.
     ///
     /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
     #[cfg(feature = "3d")]
@@ -532,8 +548,8 @@ pub struct ContactData {
     pub feature_id2: PackedFeatureId,
 }
 
-impl ContactData {
-    /// Creates a new [`ContactData`]. The contact points and normals should be given in local space.
+impl ContactPoint {
+    /// Creates a new [`ContactPoint`]. The points should be given in local space.
     ///
     /// [Feature IDs](PackedFeatureId) can be specified for the contact points using [`with_feature_ids`](Self::with_feature_ids).
     #[allow(clippy::too_many_arguments)]
@@ -596,7 +612,7 @@ impl ContactData {
         position.0 + rotation * self.point2
     }
 
-    /// Flips the contact data, swapping the points, normals, and feature IDs,
+    /// Flips the contact data, swapping the points and feature IDs,
     /// and negating the impulses.
     pub fn flip(&mut self) {
         std::mem::swap(&mut self.point1, &mut self.point2);
@@ -605,7 +621,7 @@ impl ContactData {
         self.tangent_impulse = -self.tangent_impulse;
     }
 
-    /// Returns a flipped copy of the contact data, swapping the points, normals, and feature IDs,
+    /// Returns a flipped copy of the contact data, swapping the points and feature IDs,
     /// and negating the impulses.
     pub fn flipped(&self) -> Self {
         Self {
diff --git a/src/collision/narrow_phase.rs b/src/collision/narrow_phase.rs
index 644a826a..13f18cc2 100644
--- a/src/collision/narrow_phase.rs
+++ b/src/collision/narrow_phase.rs
@@ -671,10 +671,10 @@ impl<C: AnyCollider> NarrowPhase<'_, '_, C> {
 
                 for manifold in contacts.manifolds.iter_mut() {
                     for previous_manifold in previous_contacts.manifolds.iter() {
-                        manifold.match_contacts(&previous_manifold.contacts, distance_threshold);
+                        manifold.match_contacts(&previous_manifold.points, distance_threshold);
 
                         // Add contact impulses to total impulses.
-                        for contact in manifold.contacts.iter() {
+                        for contact in manifold.points.iter() {
                             contacts.total_normal_impulse += contact.normal_impulse;
                             contacts.total_tangent_impulse += contact.tangent_impulse;
                         }
diff --git a/src/debug_render/mod.rs b/src/debug_render/mod.rs
index 7e73673d..d2f85e19 100644
--- a/src/debug_render/mod.rs
+++ b/src/debug_render/mod.rs
@@ -316,7 +316,7 @@ fn debug_render_contacts(
         };
 
         for manifold in contacts.manifolds.iter() {
-            for contact in manifold.contacts.iter() {
+            for contact in manifold.points.iter() {
                 let p1 = contact.global_point1(position1, rotation1);
                 let p2 = contact.global_point2(position2, rotation2);
 
diff --git a/src/dynamics/solver/contact/mod.rs b/src/dynamics/solver/contact/mod.rs
index 507f1c45..d2f08ee7 100644
--- a/src/dynamics/solver/contact/mod.rs
+++ b/src/dynamics/solver/contact/mod.rs
@@ -116,14 +116,14 @@ impl ContactConstraint {
             friction,
             restitution,
             normal: manifold.normal,
-            points: Vec::with_capacity(manifold.contacts.len()),
+            points: Vec::with_capacity(manifold.points.len()),
             manifold_index: manifold_id,
         };
 
         let tangents =
             constraint.tangent_directions(body1.linear_velocity.0, body2.linear_velocity.0);
 
-        for mut contact in manifold.contacts.iter().copied() {
+        for mut contact in manifold.points.iter().copied() {
             // Transform contact points from collider-space to body-space.
             if let Some(transform) = collider_transform1 {
                 contact.point1 = transform.rotation * contact.point1 + transform.translation;
diff --git a/src/dynamics/solver/mod.rs b/src/dynamics/solver/mod.rs
index 0c1ef4ce..ae45c25a 100644
--- a/src/dynamics/solver/mod.rs
+++ b/src/dynamics/solver/mod.rs
@@ -508,8 +508,7 @@ fn store_contact_impulses(
 
         let manifold = &mut contacts.manifolds[constraint.manifold_index];
 
-        for (contact, constraint_point) in
-            manifold.contacts.iter_mut().zip(constraint.points.iter())
+        for (contact, constraint_point) in manifold.points.iter_mut().zip(constraint.points.iter())
         {
             contact.normal_impulse = constraint_point.normal_part.impulse;
             contact.tangent_impulse = constraint_point

From e3e61db75bc1fefbdae778ce7c7ba2c9440421dc Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Thu, 2 Jan 2025 00:26:13 +0200
Subject: [PATCH 4/8] Rename `point1` and `point2` to `local_point1` and
 `local_point2`, fix up docs

---
 crates/avian2d/examples/custom_collider.rs |  14 +--
 src/collision/mod.rs                       | 116 +++++++++++----------
 src/dynamics/solver/contact/mod.rs         |   8 +-
 3 files changed, 73 insertions(+), 65 deletions(-)

diff --git a/crates/avian2d/examples/custom_collider.rs b/crates/avian2d/examples/custom_collider.rs
index a412d97e..f3b51385 100644
--- a/crates/avian2d/examples/custom_collider.rs
+++ b/crates/avian2d/examples/custom_collider.rs
@@ -79,21 +79,21 @@ impl AnyCollider for CircleCollider {
         let sum_radius = self.radius + other.radius;
 
         if distance_squared < (sum_radius + prediction_distance).powi(2) {
-            let normal1 = if distance_squared != 0.0 {
+            let local_normal1 = if distance_squared != 0.0 {
                 delta_pos.normalize_or_zero()
             } else {
                 Vector::X
             };
-            let normal2 = delta_rot.inverse() * (-normal1);
-            let point1 = normal1 * self.radius;
-            let point2 = normal2 * other.radius;
+            let local_normal2 = delta_rot.inverse() * (-local_normal1);
+            let local_point1 = local_normal1 * self.radius;
+            let local_point2 = local_normal2 * other.radius;
 
             vec![ContactManifold {
                 index: 0,
-                normal: rotation1 * normal1,
+                normal: rotation1 * local_normal1,
                 points: avian2d::data_structures::ArrayVec::from_iter([ContactPoint {
-                    point1,
-                    point2,
+                    local_point1,
+                    local_point2,
                     penetration: sum_radius - distance_squared.sqrt(),
                     // Impulses are computed by the constraint solver.
                     normal_impulse: 0.0,
diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index fd14e262..5a08da00 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -242,9 +242,9 @@ impl Collisions {
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct Contacts {
-    /// First entity in the contact.
+    /// The first collider entity in the contact.
     pub entity1: Entity,
-    /// Second entity in the contact.
+    /// The second collider entity in the contact.
     pub entity2: Entity,
     /// The entity of the first body involved in the contact.
     pub body_entity1: Option<Entity>,
@@ -401,13 +401,21 @@ impl ContactManifold {
                 // If the feature IDs are unknown and the contact positions match closely enough,
                 // copy the contact impulses over for warm starting.
                 if unknown_features
-                    && (contact.point1.distance_squared(previous_contact.point1)
+                    && (contact
+                        .local_point1
+                        .distance_squared(previous_contact.local_point1)
                         < distance_threshold_squared
-                        && contact.point2.distance_squared(previous_contact.point2)
+                        && contact
+                            .local_point2
+                            .distance_squared(previous_contact.local_point2)
                             < distance_threshold_squared)
-                    || (contact.point1.distance_squared(previous_contact.point2)
+                    || (contact
+                        .local_point1
+                        .distance_squared(previous_contact.local_point2)
                         < distance_threshold_squared
-                        && contact.point2.distance_squared(previous_contact.point1)
+                        && contact
+                            .local_point2
+                            .distance_squared(previous_contact.local_point1)
                             < distance_threshold_squared)
                 {
                     contact.normal_impulse = previous_contact.normal_impulse;
@@ -440,14 +448,14 @@ impl ContactManifold {
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct SingleContact {
-    /// Contact point on the first entity in local coordinates.
-    pub point1: Vector,
-    /// Contact point on the second entity in local coordinates.
-    pub point2: Vector,
-    /// A contact normal expressed in the local space of the first entity.
-    pub normal1: Vector,
-    /// A contact normal expressed in the local space of the second entity.
-    pub normal2: Vector,
+    /// The contact point on the first shape in local space.
+    pub local_point1: Vector,
+    /// The contact point on the second shape in local space.
+    pub local_point2: Vector,
+    /// The contact normal expressed in the local space of the first shape.
+    pub local_normal1: Vector,
+    /// The contact normal expressed in the local space of the second shape.
+    pub local_normal2: Vector,
     /// Penetration depth.
     pub penetration: Scalar,
 }
@@ -455,56 +463,56 @@ pub struct SingleContact {
 impl SingleContact {
     /// Creates a new [`SingleContact`]. The contact points and normals should be given in local space.
     pub fn new(
-        point1: Vector,
-        point2: Vector,
-        normal1: Vector,
-        normal2: Vector,
+        local_point1: Vector,
+        local_point2: Vector,
+        local_normal1: Vector,
+        local_normal2: Vector,
         penetration: Scalar,
     ) -> Self {
         Self {
-            point1,
-            point2,
-            normal1,
-            normal2,
+            local_point1,
+            local_point2,
+            local_normal1,
+            local_normal2,
             penetration,
         }
     }
 
-    /// Returns the global contact point on the first entity,
-    /// transforming the local point by the given entity position and rotation.
+    /// Returns the global contact point on the first shape,
+    /// transforming the local point by the given position and rotation.
     pub fn global_point1(&self, position: &Position, rotation: &Rotation) -> Vector {
-        position.0 + rotation * self.point1
+        position.0 + rotation * self.local_point1
     }
 
-    /// Returns the global contact point on the second entity,
-    /// transforming the local point by the given entity position and rotation.
+    /// Returns the global contact point on the second shape,
+    /// transforming the local point by the given position and rotation.
     pub fn global_point2(&self, position: &Position, rotation: &Rotation) -> Vector {
-        position.0 + rotation * self.point2
+        position.0 + rotation * self.local_point2
     }
 
-    /// Returns the world-space contact normal pointing towards the exterior of the first entity.
+    /// Returns the world-space contact normal pointing from the first shape to the second.
     pub fn global_normal1(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal1
+        rotation * self.local_normal1
     }
 
-    /// Returns the world-space contact normal pointing towards the exterior of the second entity.
+    /// Returns the world-space contact normal pointing from the second shape to the first.
     pub fn global_normal2(&self, rotation: &Rotation) -> Vector {
-        rotation * self.normal2
+        rotation * self.local_normal2
     }
 
     /// Flips the contact data, swapping the points and normals.
     pub fn flip(&mut self) {
-        std::mem::swap(&mut self.point1, &mut self.point2);
-        std::mem::swap(&mut self.normal1, &mut self.normal2);
+        std::mem::swap(&mut self.local_point1, &mut self.local_point2);
+        std::mem::swap(&mut self.local_normal1, &mut self.local_normal2);
     }
 
     /// Returns a flipped copy of the contact data, swapping the points and normals.
     pub fn flipped(&self) -> Self {
         Self {
-            point1: self.point2,
-            point2: self.point1,
-            normal1: self.normal2,
-            normal2: self.normal1,
+            local_point1: self.local_point2,
+            local_point2: self.local_point1,
+            local_normal1: self.local_normal2,
+            local_normal2: self.local_normal1,
             penetration: self.penetration,
         }
     }
@@ -514,10 +522,10 @@ impl SingleContact {
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 pub struct ContactPoint {
-    /// Contact point on the first entity in local coordinates.
-    pub point1: Vector,
-    /// Contact point on the second entity in local coordinates.
-    pub point2: Vector,
+    /// The contact point on the first shape in local space.
+    pub local_point1: Vector,
+    /// The contact point on the second shape in local space.
+    pub local_point2: Vector,
     /// The penetration depth.
     ///
     /// Can be negative if the objects are separated and [speculative collision] is enabled.
@@ -553,10 +561,10 @@ impl ContactPoint {
     ///
     /// [Feature IDs](PackedFeatureId) can be specified for the contact points using [`with_feature_ids`](Self::with_feature_ids).
     #[allow(clippy::too_many_arguments)]
-    pub fn new(point1: Vector, point2: Vector, penetration: Scalar) -> Self {
+    pub fn new(local_point1: Vector, local_point2: Vector, penetration: Scalar) -> Self {
         Self {
-            point1,
-            point2,
+            local_point1,
+            local_point2,
             penetration,
             normal_impulse: 0.0,
             tangent_impulse: default(),
@@ -600,22 +608,22 @@ impl ContactPoint {
         self.tangent_impulse / delta_time
     }
 
-    /// Returns the global contact point on the first entity,
-    /// transforming the local point by the given entity position and rotation.
+    /// Returns the global contact point on the first shape,
+    /// transforming the local point by the given position and rotation.
     pub fn global_point1(&self, position: &Position, rotation: &Rotation) -> Vector {
-        position.0 + rotation * self.point1
+        position.0 + rotation * self.local_point1
     }
 
-    /// Returns the global contact point on the second entity,
-    /// transforming the local point by the given entity position and rotation.
+    /// Returns the global contact point on the second shape,
+    /// transforming the local point by the given position and rotation.
     pub fn global_point2(&self, position: &Position, rotation: &Rotation) -> Vector {
-        position.0 + rotation * self.point2
+        position.0 + rotation * self.local_point2
     }
 
     /// Flips the contact data, swapping the points and feature IDs,
     /// and negating the impulses.
     pub fn flip(&mut self) {
-        std::mem::swap(&mut self.point1, &mut self.point2);
+        std::mem::swap(&mut self.local_point1, &mut self.local_point2);
         std::mem::swap(&mut self.feature_id1, &mut self.feature_id2);
         self.normal_impulse = -self.normal_impulse;
         self.tangent_impulse = -self.tangent_impulse;
@@ -625,8 +633,8 @@ impl ContactPoint {
     /// and negating the impulses.
     pub fn flipped(&self) -> Self {
         Self {
-            point1: self.point2,
-            point2: self.point1,
+            local_point1: self.local_point2,
+            local_point2: self.local_point1,
             penetration: self.penetration,
             normal_impulse: -self.normal_impulse,
             tangent_impulse: -self.tangent_impulse,
diff --git a/src/dynamics/solver/contact/mod.rs b/src/dynamics/solver/contact/mod.rs
index d2f08ee7..0742aa71 100644
--- a/src/dynamics/solver/contact/mod.rs
+++ b/src/dynamics/solver/contact/mod.rs
@@ -126,18 +126,18 @@ impl ContactConstraint {
         for mut contact in manifold.points.iter().copied() {
             // Transform contact points from collider-space to body-space.
             if let Some(transform) = collider_transform1 {
-                contact.point1 = transform.rotation * contact.point1 + transform.translation;
+                contact.local_point1 = transform.rotation * contact.local_point1 + transform.translation;
             }
             if let Some(transform) = collider_transform2 {
-                contact.point2 = transform.rotation * contact.point2 + transform.translation;
+                contact.local_point2 = transform.rotation * contact.local_point2 + transform.translation;
             }
 
             contact.penetration += collision_margin;
 
             let effective_distance = -contact.penetration;
 
-            let local_anchor1 = contact.point1 - body1.center_of_mass.0;
-            let local_anchor2 = contact.point2 - body2.center_of_mass.0;
+            let local_anchor1 = contact.local_point1 - body1.center_of_mass.0;
+            let local_anchor2 = contact.local_point2 - body2.center_of_mass.0;
 
             // Store fixed world-space anchors.
             // This improves rolling behavior for shapes like balls and capsules.

From 9e7e2d6be6243c9872dfe6ed2297d9065470eab9 Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Sun, 5 Jan 2025 19:22:22 +0200
Subject: [PATCH 5/8] Remove `total_tangent_impulse`, replace
 `total_normal_impulse` with helpers

---
 src/collision/mod.rs          | 82 ++++++++++++++++++++---------------
 src/collision/narrow_phase.rs | 11 -----
 src/debug_render/mod.rs       |  2 +-
 3 files changed, 48 insertions(+), 47 deletions(-)

diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index 5a08da00..f197c3c5 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -260,51 +260,47 @@ pub struct Contacts {
     pub during_current_frame: bool,
     /// True if the bodies were in contact during the previous frame.
     pub during_previous_frame: bool,
-    /// The total normal impulse applied to the first body in a collision.
-    ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
-    pub total_normal_impulse: Scalar,
-    /// The total tangent impulse applied to the first body in a collision.
-    ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
-    #[cfg(feature = "2d")]
-    #[doc(alias = "total_friction_impulse")]
-    pub total_tangent_impulse: Scalar,
-    /// The total tangent impulse applied to the first body in a collision.
-    ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
-    #[cfg(feature = "3d")]
-    #[doc(alias = "total_friction_impulse")]
-    pub total_tangent_impulse: Vector2,
 }
 
 impl Contacts {
-    /// The force corresponding to the total normal impulse applied over `delta_time`.
+    /// Computes the sum of all impulses applied along contact normals between the contact pair.
     ///
-    /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
-    pub fn total_normal_force(&self, delta_time: Scalar) -> Scalar {
-        self.total_normal_impulse / delta_time
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    pub fn total_normal_impulse(&self) -> Vector {
+        self.manifolds.iter().fold(Vector::ZERO, |acc, manifold| {
+            acc + manifold.normal * manifold.total_normal_impulse()
+        })
     }
 
-    /// The force corresponding to the total tangent impulse applied over `delta_time`.
+    /// Computes the sum of the magnitudes of all impulses applied along contact normals between the contact pair.
     ///
-    /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
-    #[cfg(feature = "2d")]
-    #[doc(alias = "total_friction_force")]
-    pub fn total_tangent_force(&self, delta_time: Scalar) -> Scalar {
-        self.total_tangent_impulse / delta_time
+    /// This is the sum of impulse magnitudes, *not* the magnitude of the [`total_normal_impulse`](Self::total_normal_impulse).
+    ///
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    pub fn total_normal_impulse_magnitude(&self) -> Scalar {
+        self.manifolds
+            .iter()
+            .fold(0.0, |acc, manifold| acc + manifold.total_normal_impulse())
     }
 
-    /// The force corresponding to the total tangent impulse applied over `delta_time`.
+    // TODO: We could also return a reference to the whole manifold. Would that be useful?
+    /// Finds the largest impulse between the contact pair, and the associated world-space contact normal,
+    /// pointing from the first shape to the second.
     ///
-    /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
-    #[cfg(feature = "3d")]
-    #[doc(alias = "total_friction_force")]
-    pub fn total_tangent_force(&self, delta_time: Scalar) -> Vector2 {
-        self.total_tangent_impulse / delta_time
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    pub fn max_normal_impulse(&self) -> (Scalar, Vector) {
+        let mut magnitude: Scalar = 0.0;
+        let mut normal = Vector::ZERO;
+
+        for manifold in &self.manifolds {
+            let impulse = manifold.max_normal_impulse();
+            if impulse.abs() > magnitude.abs() {
+                magnitude = impulse;
+                normal = manifold.normal;
+            }
+        }
+
+        (magnitude, normal)
     }
 
     /// Returns `true` if a collision started during the current frame.
@@ -367,6 +363,22 @@ pub struct ContactManifold {
 }
 
 impl ContactManifold {
+    /// The sum of the impulses applied at the contact points in the manifold along the contact normal.
+    fn total_normal_impulse(&self) -> Scalar {
+        self.points
+            .iter()
+            .fold(0.0, |acc, contact| acc + contact.normal_impulse)
+    }
+
+    /// The magnitude of the largest impulse applied at a contact point in the manifold along the contact normal.
+    fn max_normal_impulse(&self) -> Scalar {
+        self.points
+            .iter()
+            .map(|contact| contact.normal_impulse)
+            .max_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal))
+            .unwrap_or(0.0)
+    }
+
     /// Copies impulses from previous contacts to matching contacts in `self`.
     ///
     /// Contacts are first matched based on their [feature IDs](PackedFeatureId), and if they are unknown,
diff --git a/src/collision/narrow_phase.rs b/src/collision/narrow_phase.rs
index 13f18cc2..f3a0e920 100644
--- a/src/collision/narrow_phase.rs
+++ b/src/collision/narrow_phase.rs
@@ -645,8 +645,6 @@ impl<C: AnyCollider> NarrowPhase<'_, '_, C> {
                 || collider2.is_sensor
                 || !collider1.is_rb
                 || !collider2.is_rb,
-            total_normal_impulse: 0.0,
-            total_tangent_impulse: default(),
         };
 
         let active_hooks = collider1.active_hooks().union(collider2.active_hooks());
@@ -672,12 +670,6 @@ impl<C: AnyCollider> NarrowPhase<'_, '_, C> {
                 for manifold in contacts.manifolds.iter_mut() {
                     for previous_manifold in previous_contacts.manifolds.iter() {
                         manifold.match_contacts(&previous_manifold.points, distance_threshold);
-
-                        // Add contact impulses to total impulses.
-                        for contact in manifold.points.iter() {
-                            contacts.total_normal_impulse += contact.normal_impulse;
-                            contacts.total_tangent_impulse += contact.tangent_impulse;
-                        }
                     }
                 }
             }
@@ -776,9 +768,6 @@ pub fn reset_collision_states(
     query: Query<(Option<&RigidBody>, Has<Sleeping>)>,
 ) {
     for contacts in collisions.get_internal_mut().values_mut() {
-        contacts.total_normal_impulse = 0.0;
-        contacts.total_tangent_impulse = default();
-
         if let Ok([(rb1, sleeping1), (rb2, sleeping2)]) = query.get_many([
             contacts.body_entity1.unwrap_or(contacts.entity1),
             contacts.body_entity2.unwrap_or(contacts.entity2),
diff --git a/src/debug_render/mod.rs b/src/debug_render/mod.rs
index d2f85e19..47045fa6 100644
--- a/src/debug_render/mod.rs
+++ b/src/debug_render/mod.rs
@@ -349,7 +349,7 @@ fn debug_render_contacts(
                         * match config.contact_normal_scale {
                             ContactGizmoScale::Constant(length) => length,
                             ContactGizmoScale::Scaled(scale) => {
-                                scale * contacts.total_normal_impulse
+                                scale * contact.normal_impulse
                                     / time.delta_secs_f64().adjust_precision()
                             }
                         };

From e2305677015d5453be1ef7575d058f8fe044a471 Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Sun, 5 Jan 2025 20:11:10 +0200
Subject: [PATCH 6/8] Add back `total_normal_force` as deprecated

---
 src/collision/mod.rs | 30 +++++++++++++++++++++---------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/src/collision/mod.rs b/src/collision/mod.rs
index f197c3c5..add53e4a 100644
--- a/src/collision/mod.rs
+++ b/src/collision/mod.rs
@@ -265,7 +265,7 @@ pub struct Contacts {
 impl Contacts {
     /// Computes the sum of all impulses applied along contact normals between the contact pair.
     ///
-    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_secs()`.
     pub fn total_normal_impulse(&self) -> Vector {
         self.manifolds.iter().fold(Vector::ZERO, |acc, manifold| {
             acc + manifold.normal * manifold.total_normal_impulse()
@@ -276,7 +276,7 @@ impl Contacts {
     ///
     /// This is the sum of impulse magnitudes, *not* the magnitude of the [`total_normal_impulse`](Self::total_normal_impulse).
     ///
-    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_secs()`.
     pub fn total_normal_impulse_magnitude(&self) -> Scalar {
         self.manifolds
             .iter()
@@ -287,7 +287,7 @@ impl Contacts {
     /// Finds the largest impulse between the contact pair, and the associated world-space contact normal,
     /// pointing from the first shape to the second.
     ///
-    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time::<Substeps>::delta_secs()`.
     pub fn max_normal_impulse(&self) -> (Scalar, Vector) {
         let mut magnitude: Scalar = 0.0;
         let mut normal = Vector::ZERO;
@@ -303,6 +303,18 @@ impl Contacts {
         (magnitude, normal)
     }
 
+    /// The force corresponding to the total normal impulse applied over `delta_time`.
+    ///
+    /// Because contacts are solved over several substeps, `delta_time` should
+    /// typically use `Time<Substeps>::delta_secs()`.
+    #[deprecated(
+        note = "Use `total_normal_impulse` instead, and divide it by `Time<Substeps>::delta_secs()`",
+        since = "0.3.0"
+    )]
+    pub fn total_normal_force(&self, delta_time: Scalar) -> Scalar {
+        self.total_normal_impulse_magnitude() / delta_time
+    }
+
     /// Returns `true` if a collision started during the current frame.
     pub fn collision_started(&self) -> bool {
         !self.during_previous_frame && self.during_current_frame
@@ -546,17 +558,17 @@ pub struct ContactPoint {
     pub penetration: Scalar,
     /// The impulse applied to the first body along the contact normal.
     ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_secs()`.
     pub normal_impulse: Scalar,
     /// The impulse applied to the first body along the contact tangent. This corresponds to the impulse caused by friction.
     ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_secs()`.
     #[cfg(feature = "2d")]
     #[doc(alias = "friction_impulse")]
     pub tangent_impulse: Scalar,
     /// The impulse applied to the first body along the contact tangent. This corresponds to the impulse caused by friction.
     ///
-    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_seconds()`.
+    /// To get the corresponding force, divide the impulse by `Time<Substeps>::delta_secs()`.
     #[cfg(feature = "3d")]
     #[doc(alias = "friction_impulse")]
     pub tangent_impulse: Vector2,
@@ -595,7 +607,7 @@ impl ContactPoint {
     /// The force corresponding to the normal impulse applied over `delta_time`.
     ///
     /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
+    /// typically use `Time<Substeps>::delta_secs()`.
     pub fn normal_force(&self, delta_time: Scalar) -> Scalar {
         self.normal_impulse / delta_time
     }
@@ -603,7 +615,7 @@ impl ContactPoint {
     /// The force corresponding to the tangent impulse applied over `delta_time`.
     ///
     /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
+    /// typically use `Time<Substeps>::delta_secs()`.
     #[cfg(feature = "2d")]
     #[doc(alias = "friction_force")]
     pub fn tangent_force(&self, delta_time: Scalar) -> Scalar {
@@ -613,7 +625,7 @@ impl ContactPoint {
     /// The force corresponding to the tangent impulse applied over `delta_time`.
     ///
     /// Because contacts are solved over several substeps, `delta_time` should
-    /// typically use `Time<Substeps>::delta_seconds()`.
+    /// typically use `Time<Substeps>::delta_secs()`.
     #[cfg(feature = "3d")]
     #[doc(alias = "friction_force")]
     pub fn tangent_force(&self, delta_time: Scalar) -> Vector2 {

From 9c953d08dcff88fce00261b94ff2f92516773960 Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Sun, 5 Jan 2025 20:20:24 +0200
Subject: [PATCH 7/8] cargo fmt

---
 src/dynamics/solver/contact/mod.rs | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/dynamics/solver/contact/mod.rs b/src/dynamics/solver/contact/mod.rs
index 0742aa71..f777fba1 100644
--- a/src/dynamics/solver/contact/mod.rs
+++ b/src/dynamics/solver/contact/mod.rs
@@ -126,10 +126,12 @@ impl ContactConstraint {
         for mut contact in manifold.points.iter().copied() {
             // Transform contact points from collider-space to body-space.
             if let Some(transform) = collider_transform1 {
-                contact.local_point1 = transform.rotation * contact.local_point1 + transform.translation;
+                contact.local_point1 =
+                    transform.rotation * contact.local_point1 + transform.translation;
             }
             if let Some(transform) = collider_transform2 {
-                contact.local_point2 = transform.rotation * contact.local_point2 + transform.translation;
+                contact.local_point2 =
+                    transform.rotation * contact.local_point2 + transform.translation;
             }
 
             contact.penetration += collision_margin;

From aa4407f3a14edc52987adda33d68f7be672f31cd Mon Sep 17 00:00:00 2001
From: Joona Aalto <jondolf.dev@gmail.com>
Date: Sat, 11 Jan 2025 01:44:31 +0200
Subject: [PATCH 8/8] Update transform hash

---
 src/tests/determinism_2d.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/tests/determinism_2d.rs b/src/tests/determinism_2d.rs
index 917531a2..d2e40137 100644
--- a/src/tests/determinism_2d.rs
+++ b/src/tests/determinism_2d.rs
@@ -62,7 +62,7 @@ fn cross_platform_determinism_2d() {
     let hash = compute_hash(app.world(), query);
 
     // Update this value if simulation behavior changes.
-    let expected = 0x5b90b194;
+    let expected = 0xb9354ab8;
 
     assert!(
         hash == expected,