Rename Contacts to ContactPair (#685)

# Objective

Especially after #683, we use the term "contact pair" a lot. However, the contact pair type is called `Contacts`. This name is very ambiguous: does it represent all contacts in the world, all contacts between two entities, contacts belonging to a specific contact surface, or something else?

## Solution

Rename `Contacts` to `ContactPair`. It much more accurately describes what the type represents: contact data for a pair of entities that may be in contact. This is also the name used by Rapier.

---

## Migration Guide

`Contacts` has been renamed to `ContactPair`.

Author: Jondolf

crates/avian2d/examples/one_way_platform_2d.rs

@@ -244,7 +244,7 @@ impl CollisionHooks for PlatformerCollisionHooks<'_, '_> {
     /// Even if an entity is changed to [`PassThroughOneWayPlatform::Never`], it will be allowed to pass
     /// through a [`OneWayPlatform`] if it is already penetrating the platform. Once it exits the platform,
     /// it will no longer be allowed to pass through.
-    fn modify_contacts(&self, contacts: &mut Contacts, commands: &mut Commands) -> bool {
+    fn modify_contacts(&self, contacts: &mut ContactPair, commands: &mut Commands) -> bool {
         // This is the contact modification hook, called after collision detection,
         // but before constraints are created for the solver. Mutable access to the ECS
         // is not allowed, but we can queue commands to perform deferred changes.

crates/avian3d/examples/conveyor_belt.rs

@@ -38,14 +38,14 @@ struct ConveyorHooks<'w, 's> {
 
 // Implement the `CollisionHooks` trait for our custom system parameter.
 impl CollisionHooks for ConveyorHooks<'_, '_> {
-    fn modify_contacts(&self, contact_pair: &mut Contacts, _commands: &mut Commands) -> bool {
+    fn modify_contacts(&self, contacts: &mut ContactPair, _commands: &mut Commands) -> bool {
         // Get the conveyor belt and its global transform.
         // We don't know which entity is the conveyor belt, if any, so we need to check both.
         // This also affects the sign used for the conveyor belt's speed to apply it in the correct direction.
         let (Ok((conveyor_belt, global_transform)), sign) = self
             .conveyor_query
-            .get(contact_pair.entity1)
-            .map_or((self.conveyor_query.get(contact_pair.entity2), 1.0), |q| {
+            .get(contacts.entity1)
+            .map_or((self.conveyor_query.get(contacts.entity2), 1.0), |q| {
                 (Ok(q), -1.0)
             })
         else {
@@ -59,7 +59,7 @@ impl CollisionHooks for ConveyorHooks<'_, '_> {
 
         // Iterate over all contact surfaces between the conveyor belt and the other collider,
         // and apply a relative velocity to simulate the movement of the conveyor belt's surface.
-        for manifold in contact_pair.manifolds.iter_mut() {
+        for manifold in contacts.manifolds.iter_mut() {
             let tangent_velocity = sign * conveyor_belt.speed * direction;
             manifold.tangent_velocity = tangent_velocity.adjust_precision();
         }

crates/avian3d/examples/custom_broad_phase.rs

@@ -92,7 +92,7 @@ fn collect_collision_pairs(
             // The narrow phase will determine if the entities are touching and compute contact data.
             // NOTE: To handle sensors, collision hooks, and child colliders, you may need to configure
             //       `flags` and other properties of the contact pair. This is not done here for simplicity.
-            collisions.add_pair_with_key(Contacts::new(entity1, entity2), key);
+            collisions.add_pair_with_key(ContactPair::new(entity1, entity2), key);
         }
     }
 }

src/collision/broad_phase.rs

@@ -327,7 +327,7 @@ fn sweep_and_prune<H: CollisionHooks>(
 
             // Create a new contact pair as non-touching.
             // The narrow phase will determine if the entities are touching and compute contact data.
-            let mut contacts = Contacts::new(*entity1, *entity2);
+            let mut contacts = ContactPair::new(*entity1, *entity2);
 
             // Initialize flags and other data for the contact pair.
             contacts.body_entity1 = Some(collider_of1.rigid_body);

src/collision/contact_types/contact_graph.rs

@@ -7,7 +7,7 @@ use crate::data_structures::{
 use crate::prelude::*;
 use bevy::{platform_support::collections::HashSet, prelude::*};
 
-use super::{ContactPairFlags, Contacts};
+use super::{ContactPair, ContactPairFlags};
 
 /// A resource that stores all contact pairs in the physics world
 /// in an [undirected graph](UnGraph).
@@ -70,7 +70,7 @@ use super::{ContactPairFlags, Contacts};
 pub struct ContactGraph {
     // TODO: We could have a separate intersection graph for sensors.
     /// The internal undirected graph where nodes are entities and edges are contact pairs.
-    pub internal: UnGraph<Entity, Contacts>,
+    pub internal: UnGraph<Entity, ContactPair>,
 
     /// A set of all contact pairs for fast lookup.
     ///
@@ -89,9 +89,9 @@ impl ContactGraph {
     /// If the pair does not exist, `None` is returned.
     ///
     /// A contact pair exists between two entities if their [`ColliderAabb`]s intersect.
-    /// Use [`Contacts::is_touching`] to determine if the actual collider shapes are touching.
+    /// Use [`ContactPair::is_touching`] to determine if the actual collider shapes are touching.
     #[inline]
-    pub fn get(&self, entity1: Entity, entity2: Entity) -> Option<&Contacts> {
+    pub fn get(&self, entity1: Entity, entity2: Entity) -> Option<&ContactPair> {
         let (Some(&index1), Some(&index2)) = (
             self.entity_graph_index.get(entity1),
             self.entity_graph_index.get(entity2),
@@ -108,9 +108,9 @@ impl ContactGraph {
     /// If the pair does not exist, `None` is returned.
     ///
     /// A contact pair exists between two entities if their [`ColliderAabb`]s intersect.
-    /// Use [`Contacts::is_touching`] to determine if the actual collider shapes are touching.
+    /// Use [`ContactPair::is_touching`] to determine if the actual collider shapes are touching.
     #[inline]
-    pub fn get_mut(&mut self, entity1: Entity, entity2: Entity) -> Option<&mut Contacts> {
+    pub fn get_mut(&mut self, entity1: Entity, entity2: Entity) -> Option<&mut ContactPair> {
         let (Some(&index1), Some(&index2)) = (
             self.entity_graph_index.get(entity1),
             self.entity_graph_index.get(entity2),
@@ -150,15 +150,15 @@ impl ContactGraph {
     ///
     /// If you only want touching contacts, use [`iter_touching`](Self::iter_touching) instead.
     #[inline]
-    pub fn iter(&self) -> impl Iterator<Item = &Contacts> {
+    pub fn iter(&self) -> impl Iterator<Item = &ContactPair> {
         self.internal.all_edge_weights()
     }
 
     /// Returns an iterator yielding immutable access to all contact pairs that are currently touching.
     ///
     /// This is a subset of [`iter`](Self::iter) that only includes pairs where the colliders are touching.
     #[inline]
-    pub fn iter_touching(&self) -> impl Iterator<Item = &Contacts> {
+    pub fn iter_touching(&self) -> impl Iterator<Item = &ContactPair> {
         self.internal
             .all_edge_weights()
             .filter(|contacts| contacts.flags.contains(ContactPairFlags::TOUCHING))
@@ -171,15 +171,15 @@ impl ContactGraph {
     ///
     /// If you only want touching contacts, use [`iter_touching_mut`](Self::iter_touching_mut) instead.
     #[inline]
-    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut Contacts> {
+    pub fn iter_mut(&mut self) -> impl Iterator<Item = &mut ContactPair> {
         self.internal.all_edge_weights_mut()
     }
 
     /// Returns a iterator yielding mutable access to all contact pairs that are currently touching.
     ///
     /// This is a subset of [`iter_mut`](Self::iter_mut) that only includes pairs where the colliders are touching.
     #[inline]
-    pub fn iter_touching_mut(&mut self) -> impl Iterator<Item = &mut Contacts> {
+    pub fn iter_touching_mut(&mut self) -> impl Iterator<Item = &mut ContactPair> {
         self.internal
             .all_edge_weights_mut()
             .filter(|contacts| contacts.flags.contains(ContactPairFlags::TOUCHING))
@@ -190,9 +190,9 @@ impl ContactGraph {
     /// A contact pair exists between two entities if their [`ColliderAabb`]s intersect,
     /// even if the shapes themselves are not yet touching.
     ///
-    /// Use [`Contacts::is_touching`](Contacts::is_touching) to determine if the actual collider shapes are touching.
+    /// Use [`ContactPair::is_touching`](ContactPair::is_touching) to determine if the actual collider shapes are touching.
     #[inline]
-    pub fn collisions_with(&self, entity: Entity) -> impl Iterator<Item = &Contacts> {
+    pub fn collisions_with(&self, entity: Entity) -> impl Iterator<Item = &ContactPair> {
         self.entity_graph_index
             .get(entity)
             .into_iter()
@@ -204,9 +204,12 @@ impl ContactGraph {
     /// A contact pair exists between two entities if their [`ColliderAabb`]s intersect,
     /// even if the shapes themselves are not yet touching.
     ///
-    /// Use [`Contacts::is_touching`](Contacts::is_touching) to determine if the actual collider shapes are touching.
+    /// Use [`ContactPair::is_touching`](ContactPair::is_touching) to determine if the actual collider shapes are touching.
     #[inline]
-    pub fn collisions_with_mut(&mut self, entity: Entity) -> impl Iterator<Item = &mut Contacts> {
+    pub fn collisions_with_mut(
+        &mut self,
+        entity: Entity,
+    ) -> impl Iterator<Item = &mut ContactPair> {
         if let Some(&index) = self.entity_graph_index.get(entity) {
             self.internal.edge_weights_mut(index)
         } else {
@@ -243,7 +246,7 @@ impl ContactGraph {
     /// Creating a collision pair with this method will *not* trigger any collision events
     /// or wake up the entities involved. Only use this method if you know what you are doing.
     #[inline]
-    pub fn add_pair(&mut self, contacts: Contacts) {
+    pub fn add_pair(&mut self, contacts: ContactPair) {
         let pair_key = PairKey::new(contacts.entity1.index(), contacts.entity2.index());
         self.add_pair_with_key(contacts, pair_key);
     }
@@ -262,7 +265,7 @@ impl ContactGraph {
     /// Creating a collision pair with this method will *not* trigger any collision events
     /// or wake up the entities involved. Only use this method if you know what you are doing.
     #[inline]
-    pub fn add_pair_with_key(&mut self, contacts: Contacts, pair_key: PairKey) {
+    pub fn add_pair_with_key(&mut self, contacts: ContactPair, pair_key: PairKey) {
         // Add the pair to the pair set for fast lookup.
         if !self.pair_set.insert(pair_key) {
             // The pair already exists.
@@ -295,7 +298,7 @@ impl ContactGraph {
     /// Inserting a collision pair with this method will *not* trigger any collision events
     /// or wake up the entities involved. Only use this method if you know what you are doing.
     #[inline]
-    pub fn insert_pair(&mut self, contacts: Contacts) {
+    pub fn insert_pair(&mut self, contacts: ContactPair) {
         let pair_key = PairKey::new(contacts.entity1.index(), contacts.entity2.index());
         self.insert_pair_with_key(contacts, pair_key);
     }
@@ -314,7 +317,7 @@ impl ContactGraph {
     /// Inserting a collision pair with this method will *not* trigger any collision events
     /// or wake up the entities involved. Only use this method if you know what you are doing.
     #[inline]
-    pub fn insert_pair_with_key(&mut self, contacts: Contacts, pair_key: PairKey) {
+    pub fn insert_pair_with_key(&mut self, contacts: ContactPair, pair_key: PairKey) {
         // Add the pair to the pair set for fast lookup.
         self.pair_set.insert(pair_key);
 
@@ -344,7 +347,7 @@ impl ContactGraph {
     ///
     /// For filtering and modifying collisions, consider using [`CollisionHooks`] instead.
     #[inline]
-    pub fn remove_pair(&mut self, entity1: Entity, entity2: Entity) -> Option<Contacts> {
+    pub fn remove_pair(&mut self, entity1: Entity, entity2: Entity) -> Option<ContactPair> {
         let (Some(&index1), Some(&index2)) = (
             self.entity_graph_index.get(entity1),
             self.entity_graph_index.get(entity2),
@@ -372,7 +375,7 @@ impl ContactGraph {
     #[inline]
     pub fn remove_collider_with<F>(&mut self, entity: Entity, mut pair_callback: F)
     where
-        F: FnMut(Contacts),
+        F: FnMut(ContactPair),
     {
         let Some(&index) = self.entity_graph_index.get(entity) else {
             return;

src/collision/contact_types/mod.rs

@@ -19,7 +19,7 @@ use bevy::prelude::*;
 /// are overlapping, even if the colliders themselves are not touching.
 #[derive(Clone, Debug, PartialEq)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
-pub struct Contacts {
+pub struct ContactPair {
     /// The first collider entity in the contact.
     pub entity1: Entity,
     /// The second collider entity in the contact.
@@ -36,7 +36,7 @@ pub struct Contacts {
     pub flags: ContactPairFlags,
 }
 
-/// Flags indicating the status and type of a [contact pair](Contacts).
+/// Flags indicating the status and type of a [contact pair](ContactPair).
 #[repr(transparent)]
 #[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
 #[derive(Hash, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
@@ -62,8 +62,8 @@ bitflags::bitflags! {
     }
 }
 
-impl Contacts {
-    /// Creates a new [`Contacts`] with the given entities.
+impl ContactPair {
+    /// Creates a new [`ContactPair`] with the given entities.
     #[inline]
     pub fn new(entity1: Entity, entity2: Entity) -> Self {
         Self {

src/collision/contact_types/system_param.rs

@@ -1,7 +1,7 @@
 use crate::data_structures::pair_key::PairKey;
 use bevy::{ecs::system::SystemParam, prelude::*};
 
-use super::{ContactGraph, ContactPairFlags, Contacts};
+use super::{ContactGraph, ContactPair, ContactPairFlags};
 
 /// A [`SystemParam`] for accessing and querying collision data.
 ///
@@ -68,7 +68,7 @@ impl Collisions<'_> {
     /// Returns a touching contact pair between two entities.
     /// If the pair does not exist, `None` is returned.
     #[inline]
-    pub fn get(&self, entity1: Entity, entity2: Entity) -> Option<&Contacts> {
+    pub fn get(&self, entity1: Entity, entity2: Entity) -> Option<&ContactPair> {
         self.graph.get(entity1, entity2)
     }
 
@@ -91,7 +91,7 @@ impl Collisions<'_> {
 
     /// Returns an iterator yielding immutable access to all touching contact pairs.
     #[inline]
-    pub fn iter(&self) -> impl Iterator<Item = &Contacts> {
+    pub fn iter(&self) -> impl Iterator<Item = &ContactPair> {
         self.graph
             .iter()
             .filter(|contacts| contacts.flags.contains(ContactPairFlags::TOUCHING))
@@ -100,7 +100,7 @@ impl Collisions<'_> {
     /// Returns an iterator yielding immutable access to all touching contact pairs
     /// involving the given entity.
     #[inline]
-    pub fn collisions_with(&self, entity: Entity) -> impl Iterator<Item = &Contacts> {
+    pub fn collisions_with(&self, entity: Entity) -> impl Iterator<Item = &ContactPair> {
         self.graph
             .collisions_with(entity)
             .filter(|contacts| contacts.is_touching())

src/collision/hooks.rs

@@ -61,7 +61,7 @@ use bevy::{ecs::system::ReadOnlySystemParam, prelude::*};
 ///         group1.0 == group2.0
 ///     }
 ///
-///     fn modify_contacts(&self, contacts: &mut Contacts, _commands: &mut Commands) -> bool {
+///     fn modify_contacts(&self, contacts: &mut ContactPair, _commands: &mut Commands) -> bool {
 ///         // Allow entities to pass through the bottom and sides of one-way platforms.
 ///         // See the `one_way_platform_2d` example for a full implementation.
 ///         let (entity1, entity2) = (contacts.entity1, contacts.entity2);
@@ -73,7 +73,7 @@ use bevy::{ecs::system::ReadOnlySystemParam, prelude::*};
 /// #     entity1: Entity,
 /// #     entity2: Entity,
 /// #     platform_query: &Query<&Transform, With<OneWayPlatform>>,
-/// #     contacts: &Contacts,
+/// #     contacts: &ContactPair,
 /// # ) -> bool {
 /// #     todo!()
 /// # }
@@ -148,7 +148,7 @@ pub trait CollisionHooks: ReadOnlySystemParam + Send + Sync {
     /// A contact pair filtering hook that determines whether contacts should be computed
     /// between `entity1` and `entity2`. If `false` is returned, contacts will not be computed.
     ///
-    /// This is called in the broad phase, before [`Contacts`] have been computed for the pair.
+    /// This is called in the broad phase, before the [`ContactPair`] has been computed.
     ///
     /// The provided [`Commands`] can be used for deferred ECS operations that run after
     /// broad phase pairs have been found.
@@ -166,11 +166,11 @@ pub trait CollisionHooks: ReadOnlySystemParam + Send + Sync {
     /// A contact modification hook that allows modifying the contacts for a given contact pair.
     /// If `false` is returned, the contact pair will be removed.
     ///
-    /// This is called in the narrow phase, after [`Contacts`] have been computed for the pair,
+    /// This is called in the narrow phase, after the [`ContactPair`] has been computed for the pair,
     /// but before constraints have been generated for the contact solver.
     ///
     /// The provided [`Commands`] can be used for deferred ECS operations that run after
-    /// narrow phase [`Contacts`] have been computed and constraints have been generated.
+    /// the narrow phase has computed contact pairs and generated constraints.
     ///
     /// # Notes
     ///
@@ -180,7 +180,7 @@ pub trait CollisionHooks: ReadOnlySystemParam + Send + Sync {
     /// - Command execution order is unspecified if the `parallel` feature is enabled.
     /// - Access to the [`ContactGraph`] resource is not allowed in this method.
     ///   Trying to access it will result in a panic.
-    fn modify_contacts(&self, contacts: &mut Contacts, commands: &mut Commands) -> bool {
+    fn modify_contacts(&self, contacts: &mut ContactPair, commands: &mut Commands) -> bool {
         true
     }
 }

src/collision/narrow_phase/system_param.rs

@@ -555,7 +555,7 @@ impl<C: AnyCollider> NarrowPhase<'_, '_, C> {
     pub fn generate_constraints(
         &self,
         contact_pair_index: usize,
-        contacts: &Contacts,
+        contacts: &ContactPair,
         constraints: &mut Vec<ContactConstraint>,
         body1: &RigidBodyQueryReadOnlyItem,
         body2: &RigidBodyQueryReadOnlyItem,

src/debug_render/mod.rs

@@ -25,13 +25,13 @@ use bevy::{
 /// - [AABBs](ColliderAabb)
 /// - [Collider] wireframes
 /// - Using different colors for [sleeping](Sleeping) bodies
-/// - [Contacts]
+/// - [Contacts](ContactPair)
 /// - [Joints](dynamics::solver::joints)
 /// - [`RayCaster`]
 /// - [`ShapeCaster`]
 /// - Changing the visibility of entities to only show debug rendering
 ///
-/// By default, [AABBs](ColliderAabb) and [contacts](Contacts) are not debug rendered.
+/// By default, [AABBs](ColliderAabb) and [contacts](ContactPair) are not debug rendered.
 /// You can configure the [`PhysicsGizmos`] retrieved from `GizmoConfigStore` for the global configuration
 /// and the [`DebugRender`] component for entity-level configuration.
 ///