Per-manifold material properties and tangent velocity (#660)

# Objective

Follow-up to #610.

Now that we have contact modification hooks, we should add support for modifying the surface properties of contacts. This can enable use cases like conveyor belts or non-uniform friction and restitution for different parts of a mesh.

## Solution

Add `friction`, `restitution`, and `tangent_speed`/`tangent_velocity` properties to `ContactManifold`. These are copied over for each `ContactConstraint`.

> [!NOTE]
> **Why not have a hook for modifying `ContactConstraint` directly instead?**
>
> While we could technically do this right now, once we have wide SIMD constraints, `ContactConstraint` will also have its own SIMD version that is not as user-friendly and depends on feature flags. Providing hooks for modifying that is not very viable, and it would not be good for UX. Splitting contact modification into two hooks for different types of contact types could also be confusing for users.

The new *tangent velocity* is a way to emulate relative movement of contact surfaces, which is often used for conveyor belts. A new `conveyor_belt` example has been added to demonstrate this.

https://github.com/user-attachments/assets/3f07b4f1-6ff9-4b00-80db-5500ba43940b

Engines like Rapier, Jolt, and Box2D also have tangent velocity and other material properties, but the capabilities for contact modification are different.

- **Rapier**: Friction, restitution, and tangent velocity can be set for each solver contact point.
- **Jolt**: Friction, restitution, and tangent velocity can be set for each contact manifold.
- **Box2D**: Friction, restitution, and tangent velocity cannot be modified in pre-solve hooks, *but* friction and restitution have their own optional callbacks for basic mixing logic (I believe Jolt also has this), and chain shapes support per-segment materials. So, surface properties can only be set per shape (pair), but it is still decently flexible for 2D.

I opted for Jolt's approach of per-manifold configuration for now. It lets you have different material properties for e.g. different triangles of a trimesh, while keeping memory usage fairly minimal by not storing the properties for each individual contact point. I think this is a good balance of flexibility and cost.

If important use cases that require per-point surface properties arise, we could switch to that, but I'd prefer to keep things more simple and minimal for now.

Author: Jondolf

crates/avian2d/examples/custom_collider.rs

@@ -88,10 +88,8 @@ impl AnyCollider for CircleCollider {
             let local_point1 = local_normal1 * self.radius;
             let local_point2 = local_normal2 * other.radius;
 
-            vec![ContactManifold {
-                index: 0,
-                normal: rotation1 * local_normal1,
-                points: avian2d::data_structures::ArrayVec::from_iter([ContactPoint {
+            vec![ContactManifold::new(
+                [ContactPoint {
                     local_point1,
                     local_point2,
                     penetration: sum_radius - distance_squared.sqrt(),
@@ -100,8 +98,10 @@ impl AnyCollider for CircleCollider {
                     tangent_impulse: 0.0,
                     feature_id1: PackedFeatureId::face(0),
                     feature_id2: PackedFeatureId::face(0),
-                }]),
-            }]
+                }],
+                rotation1 * local_normal1,
+                0,
+            )]
         } else {
             vec![]
         }

crates/avian3d/Cargo.toml

@@ -119,6 +119,14 @@ required-features = ["3d", "default-collider"]
 name = "chain_3d"
 required-features = ["3d", "default-collider"]
 
+[[example]]
+name = "collider_constructors"
+required-features = ["3d", "default-collider", "bevy_scene"]
+
+[[example]]
+name = "conveyor_belt"
+required-features = ["3d", "default-collider"]
+
 [[example]]
 name = "cubes"
 required-features = ["3d", "default-collider"]
@@ -155,10 +163,6 @@ required-features = ["3d", "default-collider", "bevy_picking"]
 name = "trimesh_shapes_3d"
 required-features = ["3d", "default-collider", "bevy_scene"]
 
-[[example]]
-name = "collider_constructors"
-required-features = ["3d", "default-collider", "bevy_scene"]
-
 [[example]]
 name = "diagnostics"
 required-features = ["3d", "default-collider", "diagnostic_ui"]

crates/avian3d/examples/conveyor_belt.rs

@@ -0,0 +1,178 @@
+//! Demonstrates how to use `CollisionHooks::modify_contacts`
+//! and `tangent_velocity` to simulate conveyor belts.
+
+use avian3d::{math::*, prelude::*};
+use bevy::{
+    ecs::system::{lifetimeless::Read, SystemParam},
+    prelude::*,
+};
+use examples_common_3d::ExampleCommonPlugin;
+
+fn main() {
+    App::new()
+        .add_plugins((
+            DefaultPlugins,
+            ExampleCommonPlugin,
+            // Add our collision hooks to modify contacts for conveyor belts.
+            PhysicsPlugins::default().with_collision_hooks::<ConveyorHooks>(),
+        ))
+        .add_systems(Startup, setup)
+        .run();
+}
+
+// Enable contact modification for conveyor belts with the `ActiveCollisionHooks` component.
+// Here we use required components, but you could also add it manually.
+#[derive(Component)]
+#[require(ActiveCollisionHooks(|| ActiveCollisionHooks::MODIFY_CONTACTS))]
+struct ConveyorBelt {
+    local_direction: Vec3,
+    speed: f32,
+}
+
+// Define a custom `SystemParam` for our collision hooks.
+// It can have read-only access to queries, resources, and other system parameters.
+#[derive(SystemParam)]
+struct ConveyorHooks<'w, 's> {
+    conveyor_query: Query<'w, 's, (Read<ConveyorBelt>, Read<GlobalTransform>)>,
+}
+
+// Implement the `CollisionHooks` trait for our custom system parameter.
+impl CollisionHooks for ConveyorHooks<'_, '_> {
+    fn modify_contacts(&self, contacts: &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| {
+                (Ok(q), -1.0)
+            })
+        else {
+            // If neither entity is a conveyor belt, return `true` early
+            // to accept the contact pair without any modifications.
+            return true;
+        };
+
+        // Calculate the conveyor belt's direction in world space.
+        let direction = global_transform.rotation() * conveyor_belt.local_direction;
+
+        // 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() {
+            let tangent_velocity = sign * conveyor_belt.speed * direction;
+            manifold.tangent_velocity = tangent_velocity.adjust_precision();
+        }
+
+        // Return `true` to accept the contact pair.
+        true
+    }
+}
+
+fn setup(
+    mut commands: Commands,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+    mut meshes: ResMut<Assets<Mesh>>,
+) {
+    let long_conveyor = Cuboid::new(18.0, 0.1, 6.0);
+    let short_conveyor = Cuboid::new(14.0, 0.1, 6.0);
+
+    let long_conveyor_mesh = meshes.add(long_conveyor);
+    let short_conveyor_mesh = meshes.add(short_conveyor);
+
+    let long_conveyor_material = materials.add(Color::srgb(0.3, 0.3, 0.3));
+    let short_conveyor_material = materials.add(Color::srgb(0.2, 0.2, 0.2));
+
+    // Spawn four conveyor belts.
+    commands.spawn((
+        RigidBody::Static,
+        Collider::from(long_conveyor),
+        Friction::new(1.0),
+        ConveyorBelt {
+            local_direction: Vec3::X,
+            speed: 6.0,
+        },
+        Transform::from_xyz(-3.0, -0.25, 7.0)
+            .with_rotation(Quat::from_rotation_z(2_f32.to_radians())),
+        Mesh3d(long_conveyor_mesh.clone()),
+        MeshMaterial3d(long_conveyor_material.clone()),
+    ));
+    commands.spawn((
+        RigidBody::Static,
+        Collider::from(long_conveyor),
+        Friction::new(1.0),
+        ConveyorBelt {
+            local_direction: Vec3::NEG_X,
+            speed: 6.0,
+        },
+        Transform::from_xyz(3.0, -0.25, -7.0)
+            .with_rotation(Quat::from_rotation_z(-2_f32.to_radians())),
+        Mesh3d(long_conveyor_mesh),
+        MeshMaterial3d(long_conveyor_material.clone()),
+    ));
+    commands.spawn((
+        RigidBody::Static,
+        Collider::from(short_conveyor),
+        Friction::new(1.0),
+        ConveyorBelt {
+            local_direction: Vec3::X,
+            speed: 3.0,
+        },
+        Transform::from_xyz(9.0, -0.25, 3.0).with_rotation(
+            Quat::from_rotation_y(90_f32.to_radians()) * Quat::from_rotation_z(2_f32.to_radians()),
+        ),
+        Mesh3d(short_conveyor_mesh.clone()),
+        MeshMaterial3d(short_conveyor_material.clone()),
+    ));
+    commands.spawn((
+        RigidBody::Static,
+        Collider::from(short_conveyor),
+        Friction::new(1.0),
+        ConveyorBelt {
+            local_direction: Vec3::NEG_X,
+            speed: 3.0,
+        },
+        Transform::from_xyz(-9.0, -0.25, -3.0).with_rotation(
+            Quat::from_rotation_y(90_f32.to_radians()) * Quat::from_rotation_z(-2_f32.to_radians()),
+        ),
+        Mesh3d(short_conveyor_mesh),
+        MeshMaterial3d(short_conveyor_material),
+    ));
+
+    // Spawn cube stacks on top of one of the conveyor belts.
+    let cuboid_mesh = meshes.add(Cuboid::default());
+    let cuboid_material = materials.add(Color::srgb(0.2, 0.7, 0.9));
+    for x in -2..2 {
+        for y in 0..3 {
+            for z in -2..2 {
+                let position = Vec3::new(x as f32 + 10.0, y as f32 + 1.0, z as f32);
+                commands.spawn((
+                    RigidBody::Dynamic,
+                    // This small margin just helps prevent hitting internal edges
+                    // while sliding from one conveyor to another.
+                    CollisionMargin(0.01),
+                    Collider::cuboid(0.98, 0.98, 0.98),
+                    Transform::from_translation(position),
+                    Mesh3d(cuboid_mesh.clone()),
+                    MeshMaterial3d(cuboid_material.clone()),
+                ));
+            }
+        }
+    }
+
+    // Directional light
+    commands.spawn((
+        DirectionalLight {
+            illuminance: 5000.0,
+            shadows_enabled: true,
+            ..default()
+        },
+        Transform::default().looking_at(Vec3::new(-1.0, -2.5, -1.5), Vec3::Y),
+    ));
+
+    // Camera
+    commands.spawn((
+        Camera3d::default(),
+        Transform::from_translation(Vec3::new(20.0, 10.0, 20.0)).looking_at(Vec3::ZERO, Vec3::Y),
+    ));
+}

src/collision/contact_query.rs

@@ -195,22 +195,15 @@ pub fn contact_manifolds(
                     return vec![];
                 }
 
-                return vec![ContactManifold {
-                    normal,
-                    #[cfg(feature = "2d")]
-                    points: arrayvec::ArrayVec::from_iter([ContactPoint::new(
-                        contact.point1.into(),
-                        contact.point2.into(),
-                        -contact.dist,
-                    )]),
-                    #[cfg(feature = "3d")]
-                    points: vec![ContactPoint::new(
+                return vec![ContactManifold::new(
+                    [ContactPoint::new(
                         contact.point1.into(),
                         contact.point2.into(),
                         -contact.dist,
                     )],
-                    index: 0,
-                }];
+                    normal,
+                    0,
+                )];
             }
         }
     }
@@ -234,22 +227,18 @@ pub fn contact_manifolds(
                 return None;
             }
 
-            let manifold = ContactManifold {
+            let manifold = ContactManifold::new(
+                manifold.contacts().iter().map(|contact| {
+                    ContactPoint::new(
+                        subpos1.transform_point(&contact.local_p1).into(),
+                        subpos2.transform_point(&contact.local_p2).into(),
+                        -contact.dist,
+                    )
+                    .with_feature_ids(contact.fid1.into(), contact.fid2.into())
+                }),
                 normal,
-                points: manifold
-                    .contacts()
-                    .iter()
-                    .map(|contact| {
-                        ContactPoint::new(
-                            subpos1.transform_point(&contact.local_p1).into(),
-                            subpos2.transform_point(&contact.local_p2).into(),
-                            -contact.dist,
-                        )
-                        .with_feature_ids(contact.fid1.into(), contact.fid2.into())
-                    })
-                    .collect(),
-                index: manifold_index,
-            };
+                manifold_index,
+            );
 
             manifold_index += 1;
 

src/collision/mod.rs

@@ -373,11 +373,56 @@ pub struct ContactManifold {
     ///
     /// The same normal is shared by all `points` in a manifold,
     pub normal: Vector,
+    /// The effective coefficient of dynamic [friction](Friction) used for the contact surface.
+    pub friction: Scalar,
+    /// The effective coefficient of [restitution](Restitution) used for the contact surface.
+    pub restitution: Scalar,
+    /// The desired relative linear speed of the bodies along the surface,
+    /// expressed in world space as `tangent_speed2 - tangent_speed1`.
+    ///
+    /// Defaults to zero. If set to a non-zero value, this can be used to simulate effects
+    /// such as conveyor belts.
+    #[cfg(feature = "2d")]
+    pub tangent_speed: Scalar,
+    // TODO: Jolt also supports a relative angular surface velocity, which can be used for making
+    //       objects rotate on platforms. Would that be useful enough to warrant the extra memory usage?
+    /// The desired relative linear velocity of the bodies along the surface,
+    /// expressed in world space as `tangent_velocity2 - tangent_velocity1`.
+    ///
+    /// Defaults to zero. If set to a non-zero value, this can be used to simulate effects
+    /// such as conveyor belts.
+    #[cfg(feature = "3d")]
+    pub tangent_velocity: Vector,
     /// The index of the manifold in the collision.
     pub index: usize,
 }
 
 impl ContactManifold {
+    /// Creates a new [`ContactManifold`] with the given contact points and surface normals,
+    /// expressed in local space.
+    ///
+    /// `index` represents the index of the manifold in the collision.
+    pub fn new(
+        points: impl IntoIterator<Item = ContactPoint>,
+        normal: Vector,
+        index: usize,
+    ) -> Self {
+        Self {
+            #[cfg(feature = "2d")]
+            points: arrayvec::ArrayVec::from_iter(points),
+            #[cfg(feature = "3d")]
+            points: points.into_iter().collect(),
+            normal,
+            friction: 0.0,
+            restitution: 0.0,
+            #[cfg(feature = "2d")]
+            tangent_speed: 0.0,
+            #[cfg(feature = "3d")]
+            tangent_velocity: Vector::ZERO,
+            index,
+        }
+    }
+
     /// 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