Support custom integration and using LinearVelocity for KCCs (#899)

# Objective

Currently, for KCC movement, users must keep `LinearVelocity` at zero and manage their own externally stored velocity. Otherwise, you will end up applying the velocity twice, once by the move-and-slide algorithm, and once by the built-in position integration.

This is inconvenient, and also causes potentially incorrect collision response for dynamic bodies that bump into the kinematic body, as the contact won't consider relative velocity properly. Not good!

It would be good if users could use `LinearVelocity` even for KCCs, and simply change the way it is applied.

## Solution

Add `CustomVelocityIntegration` and `CustomPositionIntegration` components for disabling Avian's built-in integration logic. This allows users to implement their own movement driven by `LinearVelocity` and move-and-slide.

## Testing

Ran `move_and_slide_2d` and `move_and_slide_3d`.

---

## Showcase

Add the `CustomPositionIntegration` component to disable Avian's own position updates based on velocity:

```rust
commands.spawn((
    Character,
    RigidBody::Kinematic,
    Collider::from(shape),
    // We want to control position updates manually using move and slide.
    CustomPositionIntegration,
));
```

Movement systems can then simply modify `LinearVelocity`. In a way, this also makes many systems generic over dynamic and kinematic character controllers.

```rust
fn character_movement(
    mut query: Query<&mut LinearVelocity, With<Character>>,
    input: Res<ButtonInput<KeyCode>>,
) {
    for mut lin_vel in &mut query {
        // Determine movement velocity from input
        let mut delta_vel = Vec2::ZERO;
        if input.pressed(KeyCode::KeyW) {
            delta_vel += Vec2::Y
        }
        if input.pressed(KeyCode::KeyS) {
            delta_vel += Vec2::NEG_Y
        }
        if input.pressed(KeyCode::KeyA) {
            delta_vel += Vec2::NEG_X
        }
        if input.pressed(KeyCode::KeyD) {
            delta_vel += Vec2::X
        }
        delta_vel = delta_vel.normalize_or_zero();
        delta_vel *= 100.0;
        if input.pressed(KeyCode::ShiftLeft) {
            delta_vel *= 2.0;
        }

        lin_vel.0 += delta_vel.adjust_precision();
    }
}
```

You can then just run `move_and_slide` in some system, using `LinearVelocity` as the input velocity, and write the output velocity to `LinearVelocity`.

Author: Jondolf

crates/avian2d/examples/move_and_slide_2d.rs

@@ -20,21 +20,17 @@ fn main() {
                 .with_length_unit(50.0),
         ))
         .add_systems(Startup, setup)
-        .add_systems(FixedUpdate, move_player)
+        .add_systems(FixedUpdate, (player_movement, run_move_and_slide).chain())
         .add_systems(Update, update_debug_text)
         .run();
 }
 
-#[derive(Component, Default)]
-struct Player {
-    /// The velocity of the player.
-    ///
-    /// We cannot use [`LinearVelocity`] directly, because we control the transform manually,
-    /// and don't want to also apply simulation velocity on top.
-    velocity: Vec2,
-    /// The entities touched during the last `move_and_slide` call. Stored for debug printing.
-    touched: EntityHashSet,
-}
+#[derive(Component)]
+struct Player;
+
+/// The entities touched during the last `move_and_slide` call. Stored for debug printing.
+#[derive(Component, Default, Deref, DerefMut)]
+struct TouchedEntities(EntityHashSet);
 
 #[derive(Component)]
 struct DebugText;
@@ -47,13 +43,16 @@ fn setup(
     // Character
     let shape = Circle::new(30.0);
     commands.spawn((
+        Player,
         Mesh2d(meshes.add(shape)),
         MeshMaterial2d(materials.add(Color::from(tailwind::SKY_400.with_alpha(0.6)))),
         Collider::from(shape),
         RigidBody::Kinematic,
-        Player::default(),
         TransformInterpolation,
-        // Not needed for meve and slide to work, but we add it for debug printing
+        // We want to control position updates manually using move and slide.
+        CustomPositionIntegration,
+        // Store touched and colliding entities for debug printing.
+        TouchedEntities::default(),
         CollidingEntities::default(),
     ));
 
@@ -186,99 +185,121 @@ fn setup(
     ));
 }
 
-fn move_player(
-    player: Single<(Entity, &mut Transform, &mut Player, &Collider), Without<Camera>>,
-    move_and_slide: MoveAndSlide,
+/// System to handle player movement and friction.
+///
+/// This only updates velocity. The actual movement is handled by the `run_move_and_slide` system.
+fn player_movement(
+    mut query: Query<&mut LinearVelocity, With<Player>>,
     time: Res<Time>,
     input: Res<ButtonInput<KeyCode>>,
-    mut gizmos: Gizmos,
 ) {
-    let (entity, mut transform, mut player, collider) = player.into_inner();
-    let mut movement_velocity = Vec2::ZERO;
-    if input.pressed(KeyCode::KeyW) {
-        movement_velocity += Vec2::Y
-    }
-    if input.pressed(KeyCode::KeyS) {
-        movement_velocity += Vec2::NEG_Y
-    }
-    if input.pressed(KeyCode::KeyA) {
-        movement_velocity += Vec2::NEG_X
-    }
-    if input.pressed(KeyCode::KeyD) {
-        movement_velocity += Vec2::X
-    }
-    movement_velocity = movement_velocity.normalize_or_zero();
-    movement_velocity *= 100.0;
-    if input.pressed(KeyCode::ShiftLeft) {
-        movement_velocity *= 2.0;
-    }
+    for mut lin_vel in &mut query {
+        // Determine movement velocity from input
+        let mut movement_velocity = Vec2::ZERO;
+        if input.pressed(KeyCode::KeyW) {
+            movement_velocity += Vec2::Y
+        }
+        if input.pressed(KeyCode::KeyS) {
+            movement_velocity += Vec2::NEG_Y
+        }
+        if input.pressed(KeyCode::KeyA) {
+            movement_velocity += Vec2::NEG_X
+        }
+        if input.pressed(KeyCode::KeyD) {
+            movement_velocity += Vec2::X
+        }
+        movement_velocity = movement_velocity.normalize_or_zero();
+        movement_velocity *= 100.0;
+        if input.pressed(KeyCode::ShiftLeft) {
+            movement_velocity *= 2.0;
+        }
 
-    // Add velocity from last frame to preserve momentum
-    movement_velocity += player.velocity;
+        // Add to current velocity
+        lin_vel.0 += movement_velocity.adjust_precision();
 
-    let current_speed = movement_velocity.length();
-    if current_speed > 0.0 {
-        // Apply friction
-        movement_velocity = movement_velocity / current_speed
-            * (current_speed - current_speed * 20.0 * time.delta_secs()).max(0.0)
+        let current_speed = lin_vel.length();
+        if current_speed > 0.0 {
+            // Apply friction
+            lin_vel.0 = lin_vel.0 / current_speed
+                * (current_speed - current_speed * 20.0 * time.delta_secs().adjust_precision())
+                    .max(0.0)
+        }
     }
+}
 
-    player.touched.clear();
+/// System to run the move and slide algorithm, updating the player's transform and velocity.
+///
+/// This replaces Avian's default "position integration" that moves kinematic bodies based on their
+/// velocity without any collision handling.
+fn run_move_and_slide(
+    mut query: Query<
+        (
+            Entity,
+            &mut Transform,
+            &mut LinearVelocity,
+            &mut TouchedEntities,
+            &Collider,
+        ),
+        With<Player>,
+    >,
+    move_and_slide: MoveAndSlide,
+    time: Res<Time>,
+    mut gizmos: Gizmos,
+) {
+    for (entity, mut transform, mut lin_vel, mut touched, collider) in &mut query {
+        touched.clear();
 
-    // Perform move and slide
-    let MoveAndSlideOutput {
-        position,
-        projected_velocity: velocity,
-    } = move_and_slide.move_and_slide(
-        collider,
-        transform.translation.xy().adjust_precision(),
-        transform
-            .rotation
-            .to_euler(EulerRot::XYZ)
-            .2
-            .adjust_precision(),
-        movement_velocity.adjust_precision(),
-        time.delta(),
-        &MoveAndSlideConfig::default(),
-        &SpatialQueryFilter::from_excluded_entities([entity]),
-        |hit| {
-            // For each collision, draw debug gizmos
-            if hit.intersects() {
-                gizmos.circle_2d(
-                    Isometry2d::from_translation(transform.translation.xy()),
-                    33.0,
-                    tailwind::RED_600,
-                );
-            } else {
-                gizmos.arrow_2d(
-                    hit.point.f32(),
-                    (hit.point
-                        + hit.normal.adjust_precision() * hit.collision_distance
-                            / time.delta_secs().adjust_precision())
-                    .f32(),
-                    tailwind::EMERALD_400,
-                );
-            }
-            player.touched.insert(hit.entity);
-            true
-        },
-    );
+        // Perform move and slide
+        let MoveAndSlideOutput {
+            position,
+            projected_velocity,
+        } = move_and_slide.move_and_slide(
+            collider,
+            transform.translation.xy().adjust_precision(),
+            transform
+                .rotation
+                .to_euler(EulerRot::XYZ)
+                .2
+                .adjust_precision(),
+            lin_vel.0,
+            time.delta(),
+            &MoveAndSlideConfig::default(),
+            &SpatialQueryFilter::from_excluded_entities([entity]),
+            |hit| {
+                // For each collision, draw debug gizmos
+                if hit.intersects() {
+                    gizmos.circle_2d(transform.translation.xy(), 33.0, tailwind::RED_600);
+                } else {
+                    gizmos.arrow_2d(
+                        hit.point.f32(),
+                        (hit.point
+                            + hit.normal.adjust_precision() * hit.collision_distance
+                                / time.delta_secs().adjust_precision())
+                        .f32(),
+                        tailwind::EMERALD_400,
+                    );
+                }
+                touched.insert(hit.entity);
+                true
+            },
+        );
 
-    // Update transform and stored velocity
-    transform.translation = position.extend(0.0).f32();
-    player.velocity = velocity.f32();
+        // Update transform and velocity
+        transform.translation = position.extend(0.0).f32();
+        lin_vel.0 = projected_velocity;
+    }
 }
 
 fn update_debug_text(
     mut text: Single<&mut Text, With<DebugText>>,
-    player: Single<(&Player, &CollidingEntities), With<Player>>,
+    player: Single<(&LinearVelocity, &TouchedEntities, &CollidingEntities), With<Player>>,
     names: Query<NameOrEntity>,
 ) {
-    let (player, colliding_entities) = player.into_inner();
+    let (lin_vel, touched, colliding_entities) = player.into_inner();
     ***text = format!(
         "velocity: [{:.3}, {:.3}]\n{} intersections (goal is 0): {:#?}\n{} touched: {:#?}",
-        player.velocity.x,
-        player.velocity.y,
+        lin_vel.x,
+        lin_vel.y,
         colliding_entities.len(),
         names
             .iter_many(colliding_entities.iter())
@@ -287,9 +308,9 @@ fn update_debug_text(
                 .map(|n| format!("{} ({})", name.entity, n))
                 .unwrap_or_else(|| format!("{}", name.entity)))
             .collect::<Vec<_>>(),
-        player.touched.len(),
+        touched.len(),
         names
-            .iter_many(player.touched.iter())
+            .iter_many(touched.iter())
             .map(|name| name
                 .name
                 .map(|n| format!("{} ({})", name.entity, n))