Rework Contact Pair Management (#683)

# Objective

Currently, contact pair management works as follows:

1. Collect all pairs of entities with intersecting AABBs in the `BroadCollisionPairs` resource.
2. Reset collision statuses `during_previous_frame` and `during_current_frame` of each existing contact to `true` and `false` respectively.
3. Iterate over all `BroadCollisionPairs` in parallel. For each pair:
	1. Get the previous contacts from `Collisions`, if they exist, and set `during_previous_frame` accordingly.
	2. Compute new contact manifolds.
	3. Match contacts.
	4. Insert the new contact data to `Collisions`.
4. Generate contact constraints.
5. After the solver, report contacts (send collision events and update `CollidingEntities`).
6. Remove contact pairs for which `during_current_frame` is `false`.

There are a lot of inefficiencies here.

- We collect all broad phase pairs from scratch to a `Vec` every frame.
- We iterate through all collisions at least *three* separate times every frame for handling contact status changes (reset statuses, report contacts, remove ended contacts).
- We have to do a lookup for previous contacts for every contact pair.
- The logic for resetting collision statuses involves ECS queries and confusing state management.
- The parallel loop over `BroadCollisionPairs` collects collisions into new vectors every time.

Overall, there is an excessive amount of iteration and allocations, and the logic for managing contact statuses is very confusing.

In addition, the `Collisions` resource itself is not efficient for our purposes. There are many cases where you may need to iterate over contacts associated with a specific entity, but this currently requires iterating through *all* collisions because collisions are just stored in an `IndexMap`. To resolve this, we need a more graph-like structure.

## Solution

Change `Collisions` to a `ContactGraph`, and rework contact pair management to look like the following:

1. Find new broad phase pairs and add them to the `ContactGraph` directly. Duplicate pairs are avoided with fast lookups into a `HashSet<PairKey>`.
2. Iterate over all pairs in the `ContactGraph` in parallel, maintaining thread-local bit vectors to track contact status changes. For each contact pair:
	1. Test if AABBs still overlap.
	2. If the AABBs are disjoint, set `ContactPairFlags::DISJOINT_AABB` and the status change bit for this contact pair. Continue to the next pair.
	3. Otherwise, update the contact manifolds.
	4. Match contacts.
	5. Set flags for whether the contact is touching, and whether it started or stopped touching.
3. Combine thread-local bit vectors into a global bit vector with bitwise OR.
4. Serially iterate through set bits using the [count trailing zeros](https://lemire.me/blog/2018/02/21/iterating-over-set-bits-quickly/) method. For each contact pair with a changed status:
	1. If the AABBs are disjoint, send the `CollisionEnded` event (if events are enabled), update `CollidingEntities`, and remove the pair from `Collisions`.
	2. If the colliders started touching, send the `CollisionStared` event (if events are enabled) and update `CollidingEntities`.
	3. If the AABBs stopped touching, send the `CollisionEnded` event (if events are enabled) and update `CollidingEntities`.
5. Generate contact constraints.

Contact removal for removed or disabled colliders is now also handled with observers.

This improves several aspects:

- The broad phase only adds new pairs, and adds them to the `ContactGraph` directly.
- We only iterate through collisions *once* every frame for handling contact status changes, using bit scanning intrinsics to only iterate over pairs that actually changed.
- We are mutably iterating over the `ContactGraph` directly, and don't need to do separate lookups for previous contacts or do any extra allocations.

As you may have noticed, a contact pair now exists between two colliders if their AABBs are touching, even if the actual shapes aren't. This is important for the pair management logic, though it does mean that the `ContactGraph` can now have a lot more contact pairs in some cases.

### Contact Graph

Previously, `Collisions` used an `IndexMap` to store collisions, keyed by `(Entity, Entity)`. The motivation was that we get vec-like iteration speed, with preserved insertion order and fast lookups by entity pairs.

However, there are scenarios where you may need to iterate over the entities colliding with a given entity, such as for simulation islands or even gameplay logic. With just an `IndexMap`, this requires iterating over all pairs.

This PR adds an undirected graph data structure called `UnGraph`, based on [petgraph](https://github.com/petgraph/petgraph/), simplified and tailored for our use cases.

```rust
#[derive(Clone, Debug)]
pub struct UnGraph<N, E> {
    nodes: Vec<Node<N>>,
    edges: Vec<Edge<E>>,
}
```

This is used for the new `ContactGraph` to provide faster and more powerful queries over contact pairs. The following methods are available:

- `get(&self, entity1: Entity, entity2: Entity)`
- `get_mut(&mut self, entity1: Entity, entity2: Entity)`
- `contains(&self, entity1: Entity, entity2: Entity)`
- `contains_key(&self, pair_key: &PairKey)`
- `iter(&self)`
- `iter_touching(&self)`
- `iter_mut(&mut self)`
- `iter_touching_mut(&mut self)`
- `collisions_with(&self, entity: Entity)`
- `collisions_with_mut(&mut self, entity: Entity)`
- `entities_colliding_with(&self, entity: Entity)`

and a few ones primarily for internals:

- `add_pair(&mut self, contacts: Contacts)`
- `add_pair_with_key(&mut self, contacts: Contacts, pair_key: PairKey)`
- `insert_pair(&mut self, contacts: Contacts)`
- `insert_pair_with_key(&mut self, contacts: Contacts, pair_key: PairKey)`
- `remove_pair(&mut self, entity1: Entity, entity2: Entity)`
- `remove_collider_with(&mut self, entity: Entity, pair_callback: F)`

The graph doesn't let us directly get nodes or edges by `Entity` ID. However, a new `EntityDataIndex` is used to map `Entity` IDs to graph nodes.

```rust
/// A container for data associated with entities in a generational arena.
#[derive(Clone, Debug, Default)]
pub struct EntityDataIndex<T> {
    data: Vec<(u32, T)>,
}
```

This is modeled after Rapier's [`Coarena`](https://docs.rs/rapier3d/0.23.1/rapier3d/data/struct.Coarena.html).

### `Collisions` System Parameter

The `ContactGraph` resource contains both touching and non-touching contacts. This may be inconvenient and confusing for new users.

To provide a simpler, more user-friendly API, a `Collisions` `SystemParam` has been added. It is similar to the old `Collisions` resource, and only provides access to touching contacts. It doesn't allow mutation, as contact modification and filtering should typically be handled via `CollisionHooks`.

```rust
#[derive(Component)]
struct PressurePlate;

fn activate_pressure_plates(mut query: Query<Entity, With<PressurePlate>>, collisions: Collisions) {
    for pressure_plate in &query {
        // Compute the total impulse applied to the pressure plate.
        let mut total_impulse = 0.0;

        for contact_pair in collisions.collisions_with(pressure_plate) {
            total_impulse += contact_pair.total_normal_impulse_magnitude();
        }

        if total_impulse > 5.0 {
            println!("Pressure plate activated!");
        }
    }
}
```

### Contact Reporting

Previously, the `ContactReportingPlugin` sent the `CollisionStarted`, `CollisionEnded`, and `Collision` events and updated `CollidingEntities` for all contact pairs after the solver. This required iterating through all contacts and performing lots of queries, which had meaningful overhead, even for apps that don't need collision events, or only need them for a few entities.

Very few applications actually need collision events for *all* entities. In most engines, contact reporting/monitoring is entirely optional, and typically opt-in. Thus, a new `CollisionEventsEnabled` component has been added. Collision events are only sent if either entity in a collision has the component.

The `ContactReportingPlugin` has also been entirely removed, and contact reporting is now handled directly by the narrow phase when processing contact status changes. This removes the need for extra iteration or queries.

Finally, the `Collision` event has been removed. It was largely unnecessary, as the collision data can be accessed through `Collisions` directly. And semantically, it didn't feel like an "event" as it was sent every frame during continuous contact.

## Performance

In the new `pyramid_2d` example, with a pyramid that has a base of 50 boxes, 1276 total colliders, and 6 substeps, the old timings with the `parallel` feature looked like the following after 500 steps:

<img alt="Old multi-threaded" src="https://github.com/user-attachments/assets/185f68ef-3fe9-4571-9619-a4254d02f4e2" width="300" />

Now, they look like this:

<img alt="New multi-threaded" src="https://github.com/user-attachments/assets/64280006-b129-4ada-9a0a-23e0782a6288" width="300" />

Notably:

- **Narrow Phase**: 4.5x as fast, despite also handling collision events
- **Collision Events**: This whole separate step is gone, and handled by the narrow phase
- **Store Impulses**: From 0.12 ms down to 0.03 ms, because fetching contacts is handled more efficiently
- **Other**: From 0.97 ms down to 0.18 ms, largely due to `wake_on_collision_ended` being removed in favor of much more efficient logic integrated into the narrow phase

The total step time in this scene is reduced by 1.76 ms. The difference should be larger the more collisions there are.

Single-threaded performance is also improved, though not quite as much. In the same test scene, the old timings looked like this:

<img alt="Old single-threaded" src="https://github.com/user-attachments/assets/a9b6ad1f-e887-4b7f-b2fd-6ce9b4fa3fa8" width="300" />

Now, they look like this:

<img alt="New single-threaded" src="https://github.com/user-attachments/assets/08e902a0-0a6b-463a-b7a2-54f25703747b" width="300" />

reducing the total step time in this scene by 0.7 ms.

The changes in this PR also unlock many future optimizations:

- Generate contact constraints in parallel directly in the contact pair update loop
- Persistent simulation islands (benefits from a contact graph)

It is worth noting that we are currently using Bevy's built-in `ComputeTaskPool` for parallelism, which limits the number of available threads. Using it, we are still slightly behind Rapier's narrow phase performance. However, I have measured that if we manually increase the size of the thread pool, or use rayon, we now match or even slightly outperform Rapier's narrow phase.

## Future Work

- Persistent simulation islands
- Improved broad phase using [OBVHS](https://github.com/DGriffin91/obvhs)
- Rename `Contacts` to `ContactPair`
- Reuse contact manifolds and match contacts more effectively (likely not possible with Parry due to different `ContactManifold` types)

---

## Migration Guide

### `PostProcessCollisions`

The `PostProcessCollisions` schedule and `NarrowPhaseSet::PostProcess` system set have been removed, as it is incompatible with new optimizations to narrow phase collision detection. Instead, use `CollisionHooks` for contact modification.

### Contact Reporting

The `ContactReportingPlugin` and `PhysicsStepSet` have been removed. Contact reporting is now handled by the `NarrowPhasePlugin` directly.

The `Collision` event no longer exists. Instead, use `Collisions` directly, or get colliding entities using the `CollidingEntities` component.

The `CollisionStarted` and `CollisionEnded` events are now only sent if either entity in the collision has the `CollisionEventsEnabled` component. If you'd like to revert to the old behavior of having collision events for all entities, consider making `CollisionEventsEnabled` a required component for `Collider`:

```rust
app.register_required_components::<Collider, CollisionEventsEnabled>();
```

### `Collisions`

The `Collisions` resource is now a `SystemParam`.

```rust
// Old
fn iter_collisions(collisions: Res<Collisions>) {
    todo!()
}

// New
fn iter_collisions(collisions: Collisions) {
    todo!()
}
```

Internally, `Collisions` now stores a `ContactGraph` that stores both touching and non-touching contact pairs. The `Collisions` system parameter is just a wrapper that provides a simpler API and only returns touching contacts.

The `collisions_with_entity` method has also been renamed to `collisions_with`, and all methods that mutatate, add, or remove contact pairs have been removed from `Collisions`. However, the following mutating methods are available on `ContactGraph`:

- `get_mut`
- `iter_mut`
- `iter_touching_mut`
- `collisions_with_mut`
- `add_pair`/`add_pair_with_key`
- `insert_pair`/`insert_pair_with_key`
- `remove_pair`
- `remove_collider_with`

For most scenarios, contact modification and removal are intended to be handled with `CollisionHooks`.

### `Contacts`

The `is_sensor`, `during_current_frame`, and `during_previous_frame` properties of `Contacts` have been removed in favor of a `flags` property storing information in a more compact bitflag format. The `is_sensor`, `is_touching`, `collision_started`, and `collision_ended` helper methods can be used instead.

### `ContactManifold`

Methods such as `AnyCollider::contact_manifolds_with_context` now take `&mut Vec<ContactManifold>` instead of returning a new vector every time. This allows manifolds to be persisted more effectively, and reduces unnecessary allocations.

### `BroadCollisionPairs`

The `BroadCollisionPairs` resource has been removed. Use the `ContactGraph` resource instead.

### `AabbIntersections`

The `AabbIntersections` component has been removed. Use `ContactGraph::entities_colliding_with` instead.

Author: Jondolf

crates/avian2d/Cargo.toml

@@ -27,13 +27,18 @@ f64 = []
 
 debug-plugin = ["bevy/bevy_gizmos", "bevy/bevy_render"]
 simd = ["parry2d?/simd-stable", "parry2d-f64?/simd-stable"]
-parallel = ["parry2d?/parallel", "parry2d-f64?/parallel"]
+parallel = [
+    "dep:thread_local",
+    "bevy/multi_threaded",
+    "parry2d?/parallel",
+    "parry2d-f64?/parallel",
+]
 enhanced-determinism = [
     "dep:libm",
-    "parry2d?/enhanced-determinism",
-    "parry2d-f64?/enhanced-determinism",
     "bevy_math/libm",
     "bevy_heavy/libm",
+    "parry2d?/enhanced-determinism",
+    "parry2d-f64?/enhanced-determinism",
 ]
 
 default-collider = ["dep:nalgebra"]
@@ -81,11 +86,10 @@ parry2d-f64 = { version = "0.17", optional = true }
 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"
+thread_local = { version = "1.1", optional = true }
 
 [dev-dependencies]
 examples_common_2d = { path = "../examples_common_2d" }
@@ -152,6 +156,10 @@ required-features = ["2d", "default-collider"]
 name = "prismatic_joint_2d"
 required-features = ["2d", "default-collider"]
 
+[[example]]
+name = "pyramid_2d"
+required-features = ["2d", "default-collider"]
+
 [[example]]
 name = "ray_caster"
 required-features = ["2d", "default-collider"]

crates/avian2d/examples/custom_collider.rs

@@ -76,8 +76,12 @@ impl AnyCollider for CircleCollider {
         position2: Vector,
         rotation2: impl Into<Rotation>,
         prediction_distance: Scalar,
+        manifolds: &mut Vec<ContactManifold>,
         _: ContactManifoldContext<Self::Context>,
-    ) -> Vec<ContactManifold> {
+    ) {
+        // Clear the previous manifolds.
+        manifolds.clear();
+
         let rotation1: Rotation = rotation1.into();
         let rotation2: Rotation = rotation2.into();
 
@@ -98,22 +102,14 @@ impl AnyCollider for CircleCollider {
             let local_point1 = local_normal1 * self.radius;
             let local_point2 = local_normal2 * other.radius;
 
-            vec![ContactManifold::new(
-                [ContactPoint {
-                    local_point1,
-                    local_point2,
-                    penetration: sum_radius - distance_squared.sqrt(),
-                    // 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),
-                }],
-                rotation1 * local_normal1,
-                0,
-            )]
-        } else {
-            vec![]
+            let point = ContactPoint::new(
+                local_point1,
+                local_point2,
+                sum_radius - distance_squared.sqrt(),
+            )
+            .with_feature_ids(PackedFeatureId::face(0), PackedFeatureId::face(0));
+
+            manifolds.push(ContactManifold::new([point], rotation1 * local_normal1, 0));
         }
     }
 }

crates/avian2d/examples/determinism_2d.rs

@@ -19,8 +19,8 @@ use avian2d::{
     prelude::*,
 };
 use bevy::{
-    color::palettes::tailwind::CYAN_400, input::common_conditions::input_just_pressed, prelude::*,
-    render::camera::ScalingMode,
+    color::palettes::tailwind::CYAN_400, ecs::system::SystemParam,
+    input::common_conditions::input_just_pressed, prelude::*, render::camera::ScalingMode,
 };
 use bytemuck::{Pod, Zeroable};
 
@@ -34,12 +34,13 @@ fn main() {
     App::new()
         .add_plugins((
             DefaultPlugins,
-            PhysicsPlugins::default().with_length_unit(0.5),
+            PhysicsPlugins::default()
+                .with_length_unit(0.5)
+                .with_collision_hooks::<PhysicsHooks>(),
             PhysicsDebugPlugin::default(),
         ))
         .init_resource::<Step>()
         .add_systems(Startup, (setup_scene, setup_ui))
-        .add_systems(PostProcessCollisions, ignore_joint_collisions)
         .add_systems(FixedUpdate, update_hash)
         .add_systems(
             PreUpdate,
@@ -183,10 +184,22 @@ fn setup_ui(mut commands: Commands) {
     ));
 }
 
-// TODO: This should be an optimized built-in feature for joints.
-fn ignore_joint_collisions(joints: Query<&RevoluteJoint>, mut collisions: ResMut<Collisions>) {
-    for joint in &joints {
-        collisions.remove_collision_pair(joint.entity1, joint.entity2);
+#[derive(SystemParam)]
+pub struct PhysicsHooks<'w, 's> {
+    joints: Query<'w, 's, &'static RevoluteJoint>,
+}
+
+impl CollisionHooks for PhysicsHooks<'_, '_> {
+    fn filter_pairs(&self, entity1: Entity, entity2: Entity, _commands: &mut Commands) -> bool {
+        // Ignore the collision if the entities are connected by a joint.
+        // TODO: This should be an optimized built-in feature for joints.
+        self.joints
+            .iter()
+            .find(|joint| {
+                (joint.entity1 == entity1 && joint.entity2 == entity2)
+                    || (joint.entity1 == entity2 && joint.entity2 == entity1)
+            })
+            .is_some()
     }
 }
 

crates/avian2d/examples/kinematic_character_2d/plugin.rs

@@ -1,4 +1,7 @@
-use avian2d::{math::*, prelude::*};
+use avian2d::{
+    math::*,
+    prelude::{narrow_phase::NarrowPhaseSet, *},
+};
 use bevy::{ecs::query::Has, prelude::*};
 
 pub struct CharacterControllerPlugin;
@@ -23,8 +26,8 @@ impl Plugin for CharacterControllerPlugin {
                 //
                 // NOTE: The collision implementation here is very basic and a bit buggy.
                 //       A collide-and-slide algorithm would likely work better.
-                PostProcessCollisions,
-                kinematic_controller_collisions,
+                PhysicsSchedule,
+                kinematic_controller_collisions.in_set(NarrowPhaseSet::Last),
             );
     }
 }
@@ -265,7 +268,7 @@ fn apply_movement_damping(mut query: Query<(&MovementDampingFactor, &mut LinearV
 /// and predict collisions using speculative contacts.
 #[allow(clippy::type_complexity)]
 fn kinematic_controller_collisions(
-    collisions: Res<Collisions>,
+    collisions: Collisions,
     bodies: Query<&RigidBody>,
     collider_rbs: Query<&ColliderOf, Without<Sensor>>,
     mut character_controllers: Query<

crates/avian2d/examples/pyramid_2d.rs

@@ -0,0 +1,64 @@
+use avian2d::{math::Scalar, prelude::*};
+use bevy::{prelude::*, render::camera::ScalingMode};
+use examples_common_2d::ExampleCommonPlugin;
+
+fn main() {
+    let mut app = App::new();
+
+    app.add_plugins((
+        DefaultPlugins,
+        PhysicsPlugins::default(),
+        ExampleCommonPlugin,
+    ));
+
+    app.add_systems(Startup, setup);
+
+    app.run();
+}
+
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<ColorMaterial>>,
+) {
+    commands.spawn((
+        Camera2d,
+        Projection::Orthographic(OrthographicProjection {
+            scaling_mode: ScalingMode::FixedHorizontal {
+                viewport_width: 150.0,
+            },
+            ..OrthographicProjection::default_2d()
+        }),
+        Transform::from_xyz(0.0, 30.0, 0.0),
+    ));
+
+    // Ground
+    commands.spawn((
+        RigidBody::Static,
+        Collider::rectangle(800.0, 40.0),
+        Transform::from_xyz(0.0, -20.0, 0.0),
+        Mesh2d(meshes.add(Rectangle::new(800.0, 40.0))),
+        MeshMaterial2d(materials.add(Color::srgb(0.3, 0.5, 0.3))),
+    ));
+
+    let base_count = 50;
+    let h = 0.5;
+    let box_size = 2.0 * h;
+    let collider = Collider::rectangle(box_size as Scalar, box_size as Scalar);
+    let shift = h;
+    for i in 0..base_count {
+        let y = (2.0 * i as f32 + 1.0) * shift * 0.99;
+
+        for j in i..base_count {
+            let x = (i as f32 + 1.0) * shift + 2.0 * (j - i) as f32 * shift - h * base_count as f32;
+
+            commands.spawn((
+                RigidBody::Dynamic,
+                collider.clone(),
+                Transform::from_xyz(x, y, 0.0),
+                Mesh2d(meshes.add(Rectangle::new(box_size, box_size))),
+                MeshMaterial2d(materials.add(Color::srgb(0.2, 0.7, 0.9))),
+            ));
+        }
+    }
+}

crates/avian2d/examples/sensor.rs

@@ -67,6 +67,8 @@ fn setup(
         Sensor,
         RigidBody::Static,
         Collider::rectangle(100.0, 100.0),
+        // Enable collision events for this entity.
+        CollisionEventsEnabled,
         // Read entities colliding with this entity.
         CollidingEntities::default(),
     ));

crates/avian3d/Cargo.toml

@@ -28,13 +28,18 @@ f64 = []
 
 debug-plugin = ["bevy/bevy_gizmos", "bevy/bevy_render"]
 simd = ["parry3d?/simd-stable", "parry3d-f64?/simd-stable"]
-parallel = ["parry3d?/parallel", "parry3d-f64?/parallel"]
+parallel = [
+    "dep:thread_local",
+    "bevy/multi_threaded",
+    "parry3d?/parallel",
+    "parry3d-f64?/parallel",
+]
 enhanced-determinism = [
     "dep:libm",
-    "parry3d?/enhanced-determinism",
-    "parry3d-f64?/enhanced-determinism",
     "bevy_math/libm",
     "bevy_heavy/libm",
+    "parry3d?/enhanced-determinism",
+    "parry3d-f64?/enhanced-determinism",
 ]
 
 default-collider = ["dep:nalgebra"]
@@ -83,11 +88,10 @@ parry3d-f64 = { version = "0.17", optional = true }
 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"
+thread_local = { version = "1.1", optional = true }
 
 [dev-dependencies]
 examples_common_3d = { path = "../examples_common_3d" }

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, contacts: &mut Contacts, _commands: &mut Commands) -> bool {
+    fn modify_contacts(&self, contact_pair: &mut Contacts, _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(contacts.entity1)
-            .map_or((self.conveyor_query.get(contacts.entity2), 1.0), |q| {
+            .get(contact_pair.entity1)
+            .map_or((self.conveyor_query.get(contact_pair.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 contacts.manifolds.iter_mut() {
+        for manifold in contact_pair.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

@@ -1,4 +1,4 @@
-use avian3d::{math::*, prelude::*};
+use avian3d::{data_structures::pair_key::PairKey, math::*, prelude::*};
 use bevy::prelude::*;
 use examples_common_3d::ExampleCommonPlugin;
 
@@ -7,7 +7,7 @@ fn main() {
 
     app.add_plugins((DefaultPlugins, ExampleCommonPlugin));
 
-    // Add PhysicsPlugins and replace the default broad phase with our custom broad phase.
+    // Add `PhysicsPlugins` and replace the default broad phase with our custom broad phase.
     app.add_plugins(
         PhysicsPlugins::default()
             .build()
@@ -56,37 +56,43 @@ fn setup(
     ));
 }
 
-// Collects pairs of potentially colliding entities into the BroadCollisionPairs resource provided by the physics engine.
+/// Finds pairs of entities with overlapping `ColliderAabb`s
+/// and creates contact pairs for them in the `ContactGraph`.
+///
 // A brute force algorithm is used for simplicity.
 pub struct BruteForceBroadPhasePlugin;
 
 impl Plugin for BruteForceBroadPhasePlugin {
     fn build(&self, app: &mut App) {
-        // Initialize the resource that the collision pairs are added to.
-        app.init_resource::<BroadCollisionPairs>();
-
-        // Make sure the PhysicsSchedule is available.
-        let physics_schedule = app
-            .get_schedule_mut(PhysicsSchedule)
-            .expect("add PhysicsSchedule first");
-
-        // Add the broad phase system into the broad phase set
-        physics_schedule.add_systems(collect_collision_pairs.in_set(PhysicsStepSet::BroadPhase));
+        // Add the broad phase system into the broad phase set.
+        app.add_systems(
+            PhysicsSchedule,
+            collect_collision_pairs.in_set(PhysicsStepSet::BroadPhase),
+        );
     }
 }
 
 fn collect_collision_pairs(
     bodies: Query<(Entity, &ColliderAabb, &RigidBody)>,
-    mut broad_collision_pairs: ResMut<BroadCollisionPairs>,
+    mut collisions: ResMut<ContactGraph>,
 ) {
-    // Clear old collision pairs.
-    broad_collision_pairs.0.clear();
-
     // Loop through all entity combinations and collect pairs of bodies with intersecting AABBs.
-    for [(ent_a, aabb_a, rb_a), (ent_b, aabb_b, rb_b)] in bodies.iter_combinations() {
-        // At least one of the bodies is dynamic and their AABBs intersect
-        if (rb_a.is_dynamic() || rb_b.is_dynamic()) && aabb_a.intersects(aabb_b) {
-            broad_collision_pairs.0.push((ent_a, ent_b));
+    for [(entity1, aabb1, rb1), (entity2, aabb2, rb2)] in bodies.iter_combinations() {
+        // At least one of the bodies is dynamic and their AABBs intersect.
+        if (rb1.is_dynamic() || rb2.is_dynamic()) && aabb1.intersects(aabb2) {
+            // Create a pair key from the entity indices.
+            let key = PairKey::new(entity1.index(), entity2.index());
+
+            // Avoid duplicate pairs.
+            if collisions.contains_key(&key) {
+                continue;
+            }
+
+            // Create a contact pair as non-touching.
+            // 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);
         }
     }
 }