Struct MoveAndSlide 

pub struct MoveAndSlide<'w, 's> {
    pub spatial_query: SpatialQuery<'w, 's>,
    pub colliders: Query<'w, 's, (&'static Collider, &'static Position, &'static Rotation, Option<&'static CollisionLayers>), (With<ColliderOf>, Without<Sensor>)>,
    pub length_unit: Res<'w, PhysicsLengthUnit>,
}

A SystemParam for the move and slide algorithm, also known as collide and slide or step slide.

Move and slide is the core movement and collision algorithm used by most kinematic character controllers. It attempts to move a shape along a desired velocity vector, sliding along any colliders that are hit on the way.

Algorithm

At a high level, the algorithm works as follows:

1. Sweep the shape along the desired velocity vector.
2. If no collision is detected, move the full distance.
3. If a collision is detected:
   • Move up to the point of collision.
   • Project the remaining velocity onto the contact surfaces to obtain a new sliding velocity.
4. Repeat with the new sliding velocity until movement is complete.

The algorithm also includes depenetration passes before and after movement to improve stability and ensure that the shape does not intersect any colliders.

Configuration

MoveAndSlideConfig allows configuring various aspects of the algorithm. See its documentation for more information.

Additionally, move_and_slide can be given a callback that is called for each contact surface that is detected during movement. This allows for custom handling of collisions, such as triggering events, or modifying movement based on specific colliders.

Other Utilities

In addition to the main move_and_slide method, this system parameter also provides utilities for:

• Performing shape casts optimized for movement via cast_move.
• Depenetrating shapes that are intersecting colliders via depenetrate.
• Performing intersection tests via intersections.
• Projecting velocities to slide along contact planes via project_velocity.

These methods are used internally by the move and slide algorithm, but can also be used independently for custom movement and collision handling.

Resources

Some useful resources for learning more about the move and slide algorithm include:

• Collide And Slide - *Actually Decent* Character Collision From Scratch by Poke Dev (video)
• PM_SlideMove in Quake III Arena (source code)

Note that while the high-level concepts are similar across different implementations, details may vary.

Fields

spatial_query: SpatialQuery<'w, 's>

The SpatialQuery system parameter used to perform shape casts and other geometric queries.

colliders: Query<'w, 's, (&'static Collider, &'static Position, &'static Rotation, Option<&'static CollisionLayers>), (With<ColliderOf>, Without<Sensor>)>

The Query used to query for colliders.

length_unit: Res<'w, PhysicsLengthUnit>

A units-per-meter scaling factor that adjusts some thresholds and tolerances to the scale of the world for better behavior.

Implementations

impl<'w, 's> MoveAndSlide<'w, 's>

pub fn move_and_slide( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, velocity: Vector, delta_time: Duration, config: &MoveAndSlideConfig, filter: &SpatialQueryFilter, on_hit: impl FnMut(MoveAndSlideHitData<'_>) -> MoveAndSlideHitResponse, ) -> MoveAndSlideOutput

Moves a shape along a given velocity vector, sliding along any colliders that are hit on the way.

See MoveAndSlide for an overview of the algorithm.

Arguments

• shape: The shape being cast represented as a Collider.
• shape_position: Where the shape is cast from.
• shape_rotation: The rotation of the shape being cast.
• velocity: The initial velocity vector along which to move the shape. This will be modified to reflect sliding along surfaces.
• delta_time: The duration over which to move the shape. velocity * delta_time gives the total desired movement vector.
• config: A MoveAndSlideConfig that determines the behavior of the move and slide. MoveAndSlideConfig::default() should be a good start for most cases.
• filter: A SpatialQueryFilter that determines which colliders are taken into account in the query. It is highly recommended to exclude the entity holding the collider itself, otherwise the character will collide with itself.
• on_hit: A callback that is called when a collider is hit as part of the move and slide iterations. The returned MoveAndSlideHitResponse determines how to handle the hit. If you don’t have any special handling per collision, you can pass |_| MoveAndSlideHitResponse::Accept.

Example

use bevy::prelude::*;
use std::collections::HashSet;
use avian3d::{prelude::*, math::{Vector, AdjustPrecision as _, AsF32 as _}};

#[derive(Component)]
struct CharacterController {
    velocity: Vector,
}

fn perform_move_and_slide(
    player: Single<(Entity, &Collider, &mut CharacterController, &mut Transform)>,
    move_and_slide: MoveAndSlide,
    time: Res<Time>
) {
    let (entity, collider, mut controller, mut transform) = player.into_inner();
    let velocity = controller.velocity + Vector::X * 10.0;
    let filter = SpatialQueryFilter::from_excluded_entities([entity]);
    let mut collisions = HashSet::new();
    let out = move_and_slide.move_and_slide(
        collider,
         transform.translation.adjust_precision(),
         transform.rotation.adjust_precision(),
        velocity,
        time.delta(),
        &MoveAndSlideConfig::default(),
        &filter,
        |hit| {
            collisions.insert(hit.entity);
            MoveAndSlideHitResponse::Accept
        },
    );
     transform.translation = out.position.f32();
    controller.velocity = out.projected_velocity;
    info!("Colliding with entities: {:?}", collisions);
}

pub fn cast_move( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, movement: Vector, skin_width: Scalar, filter: &SpatialQueryFilter, ) -> Option<MoveHitData>

A shape cast optimized for movement. Use this if you want to move a collider with a given velocity and stop so that it keeps a distance of skin_width from the first collider on its path.

This operation is most useful when you ensure that the character is not intersecting any colliders before moving. To do this, call MoveAndSlide::depenetrate and add the resulting offset vector to the character’s position before calling this method. See the example below.

It is often useful to clip the velocity afterwards so that it no longer points into the contact plane using Self::project_velocity.

Arguments

• shape: The shape being cast represented as a Collider.
• shape_position: Where the shape is cast from.
• shape_rotation: The rotation of the shape being cast.
• movement: The direction and magnitude of the movement. If this is Vector::ZERO, this method can still return Some(MoveHitData) if the shape started off intersecting a collider.
• skin_width: A ShapeCastConfig that determines the behavior of the cast.
• filter: A SpatialQueryFilter that determines which colliders are taken into account in the query. It is highly recommended to exclude the entity holding the collider itself, otherwise the character will collide with itself.

Returns

• Some(MoveHitData) if the shape hit a collider on the way, or started off intersecting a collider.
• None if the shape is able to move the full distance without hitting a collider.

Example

use bevy::prelude::*;
use avian3d::{prelude::*, math::{Vector, Dir, AdjustPrecision as _, AsF32 as _}};

#[derive(Component)]
struct CharacterController {
    velocity: Vector,
}

fn perform_cast_move(
    player: Single<(Entity, &Collider, &mut CharacterController, &mut Transform)>,
    move_and_slide: MoveAndSlide,
    time: Res<Time>
) {
    let (entity, collider, mut controller, mut transform) = player.into_inner();
    let filter = SpatialQueryFilter::from_excluded_entities([entity]);
    let config = MoveAndSlideConfig::default();

    // Ensure that the character is not intersecting with any colliders.
    let offset = move_and_slide.depenetrate(
        collider,
         transform.translation.adjust_precision(),
         transform.rotation.adjust_precision(),
        &((&config).into()),
        &filter,
    );
     transform.translation += offset.f32();
    let velocity = controller.velocity;

    let hit = move_and_slide.cast_move(
        collider,
         transform.translation.adjust_precision(),
         transform.rotation.adjust_precision(),
        velocity * time.delta_secs().adjust_precision(),
        config.skin_width,
        &filter,
    );
    if let Some(hit) = hit {
        // We collided with something on the way. Advance as much as possible.
         transform.translation += (velocity.normalize_or_zero() * hit.distance).f32();
        // Then project the velocity to make sure it no longer points towards the contact plane.
        controller.velocity =
            MoveAndSlide::project_velocity(velocity, &[Dir::new_unchecked(hit.normal1.f32())])
    } else {
        // We traveled the full distance without colliding.
         transform.translation += velocity.f32();
    }
}

Related methods

• SpatialQuery::cast_shape

pub fn depenetrate( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, config: &DepenetrationConfig, filter: &SpatialQueryFilter, ) -> Vector

Moves a collider so that it no longer intersects any other collider and keeps a minimum distance of DepenetrationConfig::skin_width scaled by the PhysicsLengthUnit.

Depenetration is an iterative process that solves penetrations for all planes, until we either reached MoveAndSlideConfig::move_and_slide_iterations or the accumulated error is less than MoveAndSlideConfig::max_depenetration_error. If the maximum number of iterations was reached before the error is below the threshold, the current best attempt is returned, in which case the collider may still be intersecting with other colliders.

This method is equivalent to calling Self::depenetrate_intersections with the results of Self::intersections.

Arguments

• shape: The shape that intersections are tested against represented as a Collider.
• shape_position: The position of the shape.
• shape_rotation: The rotation of the shape.
• config: A DepenetrationConfig that determines the behavior of the depenetration. DepenetrationConfig::default() should be a good start for most cases.
• filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.

Example

use bevy::prelude::*;
use avian3d::{prelude::*, character_controller::move_and_slide::DepenetrationConfig, math::{AdjustPrecision as _, AsF32 as _}};
fn depenetrate_player(
    player: Single<(Entity, &Collider, &mut Transform)>,
    move_and_slide: MoveAndSlide,
    time: Res<Time>
) {
    let (entity, collider, mut transform) = player.into_inner();
    let filter = SpatialQueryFilter::from_excluded_entities([entity]);

    let offset = move_and_slide.depenetrate(
        collider,
         transform.translation.adjust_precision(),
         transform.rotation.adjust_precision(),
        &DepenetrationConfig::default(),
        &filter,
    );
     transform.translation += offset.f32();
}

See also MoveAndSlide::cast_move for a typical usage scenario.

Related methods

• MoveAndSlide::intersections
• MoveAndSlide::depenetrate_intersections

pub fn depenetrate_intersections( &self, config: &DepenetrationConfig, intersections: &[(Dir, Scalar)], ) -> Vector

Manual version of MoveAndSlide::depenetrate.

Moves a collider so that it no longer intersects any other collider and keeps a minimum distance of DepenetrationConfig::skin_width scaled by the PhysicsLengthUnit. The intersections should be provided as a list of contact plane normals and penetration distances, which can be obtained via MoveAndSlide::intersections.

Depenetration is an iterative process that solves penetrations for all planes, until we either reached MoveAndSlideConfig::move_and_slide_iterations or the accumulated error is less than MoveAndSlideConfig::max_depenetration_error. If the maximum number of iterations was reached before the error is below the threshold, the current best attempt is returned, in which case the collider may still be intersecting with other colliders.

Arguments

• config: A DepenetrationConfig that determines the behavior of the depenetration. DepenetrationConfig::default() should be a good start for most cases.
• intersections: A list of contact plane normals and penetration distances representing the intersections to resolve.

Returns

A displacement vector that can be added to the shape_position to resolve the intersections, or the best attempt if the max iterations were reached before a solution was found.

Example

use bevy::prelude::*;
use avian3d::{prelude::*, character_controller::move_and_slide::DepenetrationConfig, math::{AdjustPrecision as _, AsF32 as _}};
fn depenetrate_player_manually(
    player: Single<(Entity, &Collider, &mut Transform)>,
    move_and_slide: MoveAndSlide,
    time: Res<Time>
) {
    let (entity, collider, mut transform) = player.into_inner();
    let filter = SpatialQueryFilter::from_excluded_entities([entity]);
    let config = DepenetrationConfig::default();

    let mut intersections = Vec::new();
    move_and_slide.intersections(
        collider,
         transform.translation.adjust_precision(),
         transform.rotation.adjust_precision(),
        config.skin_width,
        &filter,
        |contact_point, normal| {
            intersections.push((normal, contact_point.penetration + config.skin_width));
            true
        },
    );
    let offset = move_and_slide.depenetrate_intersections(&config, &intersections);
     transform.translation += offset.f32();
}

Related methods

• MoveAndSlide::intersections
• MoveAndSlide::depenetrate

pub fn intersections( &self, shape: &Collider, shape_position: Vector, shape_rotation: Quaternion, prediction_distance: Scalar, filter: &SpatialQueryFilter, callback: impl FnMut(&ContactPoint, Dir) -> bool, )

An intersection test that calls a callback for each Collider found that is closer to the given shape with a given position and rotation than prediction_distance.

Arguments

• shape: The shape that intersections are tested against represented as a Collider.
• shape_position: The position of the shape.
• shape_rotation: The rotation of the shape.
• filter: A SpatialQueryFilter that determines which colliders are taken into account in the query.
• prediction_distance: An extra margin applied to the Collider.
• callback: A callback that is called for each intersection found. The callback receives the deepest contact point and the contact normal. Returning false will stop further processing of intersections.

Example

See MoveAndSlide::depenetrate_intersections for a typical usage scenario.

Related methods

• MoveAndSlide::depenetrate_intersections
• MoveAndSlide::depenetrate

pub fn project_velocity(v: Vector, normals: &[Dir]) -> Vector

Projects input velocity v onto the planes defined by the given normals. This ensures that velocity does not point into any of the planes, but along them.

This is often used after MoveAndSlide::cast_move to ensure a character moved that way does not try to continue moving into colliding geometry.

Trait Implementations

impl SystemParam for MoveAndSlide<'_, '_>

type State = FetchState

Used to store data which persists across invocations of a system.

type Item<'w, 's> = MoveAndSlide<'w, 's>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state(world: &mut World) -> Self::State

Creates a new instance of this param’s State.

fn init_access( state: &Self::State, system_meta: &mut SystemMeta, component_access_set: &mut FilteredAccessSet, world: &mut World, )

Registers any World access used by this SystemParam

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during ApplyDeferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next ApplyDeferred.

unsafe fn validate_param<'w, 's>( state: &'s mut Self::State, _system_meta: &SystemMeta, _world: UnsafeWorldCell<'w>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

unsafe fn get_param<'w, 's>( state: &'s mut Self::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> Self::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

impl<'w, 's> ReadOnlySystemParam for MoveAndSlide<'w, 's>

where SpatialQuery<'w, 's>: ReadOnlySystemParam, Query<'w, 's, (&'static Collider, &'static Position, &'static Rotation, Option<&'static CollisionLayers>), (With<ColliderOf>, Without<Sensor>)>: ReadOnlySystemParam, Res<'w, PhysicsLengthUnit>: ReadOnlySystemParam,