Skip to main content

Controllers

A controller is a higher-level tool computing the motion of a body from what your application asks for, rather than leaving it entirely to the forces of the simulation. Rapier provides:

Character controller​

Most games involve bodies behaving in ways that defy the laws of physics: floating platforms, elevators, playable characters, etc. This is why kinematic bodies exist: they offer a total control over the body’s trajectory since they are completely immune to forces or impulses (like gravity, contacts, joints).

But this control comes at a price: it is up to the user to take any obstacle into account by running custom collision-detection operations manually and update the trajectory accordingly. This can be very difficult. Detecting obstacles usually rely on ray-casting or shape-casting, used to adjust the trajectory based on the potential contact normals. Often, multiple ray or shape-casts are needed, and the trajectory adjustment code isn’t straightforward.

The Kinematic Character Controller (which we will abbreviate to character controller) is a higher-level tool that will emit the proper ray-casts and shape-casts to adjust the user-defined trajectory based on obstacles. The well-known move-and-slide operation is the main feature of a character controller.

note

Despite its name, a character controller can also be used for moving objects that are not characters. For example, a character controller may be used to move a platform. In the rest of this guide, we will use the word character to designate whatever you would like to move using the character controller.

Rapier provides a built-in general-purpose character controller implementation. It allows you to easily:

  • Stop at obstacles.
  • Slide on slopes that are not to steep.
  • Climb stairs automatically.
  • Walk over small obstacles.
  • Interact with moving platforms.

Despite the fact that this built-in character controller is designed to be generic enough to serve as a good starting point for many common use-cases, character-control (especially for the player’s character itself) is often very game-specific. Therefore the builtin character controller may not work perfectly out-of-the-box for all game types. Don’t hesitate to copy and customize it to fit your particular needs.

Setup and usage​

The character controller implementation is exposed as the KinematicCharacterController structure. This structure only contains information about the character controller’s behavior. It does not contain any collider-specific or rigid-body-specific information like handles, velocities, positions, etc. Therefore, the same instance of KinematicCharacterController can be used to control multiple rigid-bodies/colliders if they rely on the same set of parameters. The KinematicCharacterController exposes only two methods:

  • move_shape is responsible for calculating the possible movement of a character based on the desired movement, obstacles, and character controller options.
  • solve_character_collision_impulses is detailed in the collisions section.
// The translation we would like to apply if there were no obstacles.
let desired_translation = Vector::new(1.0, -2.0);
// Create the character controller, here with the default configuration.
let character_controller = KinematicCharacterController::default();
// Init the query pipeline.
let filter = QueryFilter::default()
    // Make sure the character we are trying to move isn’t considered an obstacle.
    .exclude_rigid_body(rigid_body_handle);
let query_pipeline = world.query_pipeline_with_filter(filter);
// Calculate the possible movement.
let corrected_movement = character_controller.move_shape(
    dt,              // The timestep length (can be set to SimulationSettings::dt).
    &query_pipeline, // The query pipeline.
    character_shape, // The character’s shape.
    character_pos,   // The character’s initial position.
    desired_translation,
    |_| {}, // We don’t care about events in this example.
);
// TODO: apply the `corrected_movement.translation` to the rigid-body or collider based on the rules described below.

The recommended way to update the character’s position depends on its representation:

  • A collider not attached to any rigid-body: set the collider’s position directly to the corrected movement added to its current position.
  • A velocity-based kinematic rigid-body: set its velocity to the computed movement divided by the timestep length.
  • A position-based kinematic rigid-body: set its next kinematic position to the corrected movement added to its current position.
info

The character’s shape may be any shape supported by Rapier. However, it is recommended to either use a cuboid, a ball, or a capsule since they involve less computations and less numerical approximations.

warning

The built-in character controller does not support rotational movement. It only supports translations.

Character offset​

For performance and numerical stability reasons, the character controller will attempt to preserve a small gap between the character shape and the environment. This small gap is named offset and acts as a small margin around the character shape. A good value for this offset is something sufficiently small to make the gap unnoticeable, but sufficiently large to avoid numerical issues (if the character seems to get stuck inexplicably, try increasing the offset).

character offset

// The character offset is set to 0.01.
character_controller.offset = CharacterLength::Absolute(0.01);
// The character offset is set to 0.01 multiplied by the shape’s height.
character_controller.offset = CharacterLength::Relative(0.01);
warning

It is not recommended to change the offset after the creation of the character controller.

Up vector​

The up vector instructs the character controller of what direction should be considered vertical. The horizontal plane is the plane orthogonal to this up vector. There are two equivalent ways to evaluate the slope of the floor: by taking the angle between the floor and the horizontal plane (in 2D), or by taking the angle between the up-vector and the normal of the floor (in 2D and 3D). By default, the up vector is the positive y axis, but it can be modified to be any (unit) vector that suits the application.

up vector and slope angles

// Set the up-vector to the positive X axis.
character_controller.up = Vector::X;

Slopes​

If sliding is enabled, the character can automatically climb slopes if they are not too steep, or slide down slopes if they are too steep. Sliding is configured by the following parameters:

  • The max slope climb angle: if the angle between the slope to climb and the horizontal floor is larger than this value, then the character won’t be able to slide up this slope.
  • The min slope slide angle: if the angle between the slope and the horizontal floor is smaller than this value, then the vertical component of the character’s movement won’t result in any sliding.
info

As always in Rapier, angles are specified in radians.

// Don’t allow climbing slopes larger than 45 degrees.
character_controller.max_slope_climb_angle = 45_f32.to_radians();
// Automatically slide down on slopes smaller than 30 degrees.
character_controller.min_slope_slide_angle = 30_f32.to_radians();

Stairs and small obstacles​

If enabled, the autostep setting allows the character to climb stairs automatically and walk over small obstacles. Autostepping requires the following parameters:

  • The maximum height the character can step over. If the vertical movement needed to step over this obstacle is larger than this value, then the character will be stopped by the obstacle.
  • The minimum (horizontal) width available on top of the obstacle. If, after the character is teleported on top of the obstacle, it cannot move forward by a distance larger than this minimum width, then the character will just be stopped by the obstacle (without being moved to the top of the obstacle).
  • Whether or not autostepping is enabled for dynamic bodies. If it is not enabled for dynamic bodies, the character won’t attempt to automatically step over small dynamic bodies. Disabling this can be useful if we want the character to push these small objects (see collisions) instead of just stepping over them.

The following depicts (top) one configuration where all the autostepping conditions are satisfied, and, (bottom) two configurations where these conditions are not all satisfied (left: because the width of the step is too small, right: because the height of the step is too large):

autostepping

info

Autostepping will only activate if the character is touching the floor right before the obstacle. This prevents the player from being teleported on to of a platform while it is in the air.

// Set autostep to None to disable it.
character_controller.autostep = None;
// Autostep if the step height is smaller than 0.5, and its width larger than 0.2.
character_controller.autostep = Some(CharacterAutostep {
    max_height: CharacterLength::Absolute(0.5),
    min_width: CharacterLength::Absolute(0.2),
    include_dynamic_bodies: true,
});
// Autostep if the step height is smaller than 0.3 multiplied by the character’s height,
// and its width larger than 0.5 multiplied by the character’s width (i.e. half the character’s
// width).
character_controller.autostep = Some(CharacterAutostep {
    max_height: CharacterLength::Relative(0.3),
    min_width: CharacterLength::Relative(0.5),
    include_dynamic_bodies: true,
});

Snap-to-ground​

If enabled, snap-to-ground will force the character to stick to the ground if the following conditions are met simultaneously:

  • At the start of the movement, the character touches the ground.
  • The movement has a slight downward component.
  • At the end of the desired movement, the character would be separated from the ground by a distance smaller than the distance provided by the snap-to-ground parameter.

If these conditions are met, the character is automatically teleported down to the ground at the end of its motion. Typical usages of snap-to-ground include going downstairs or remaining in contact with the floor when moving downhill.

snap-to-ground

// Set snap-to-ground to None to disable it.
character_controller.snap_to_ground = None;
// Snap to the ground if the vertical distance to the ground is smaller than 0.5.
character_controller.snap_to_ground = Some(CharacterLength::Absolute(0.5));
// Snap to the ground if the vertical distance to the ground is smaller than 0.2 times the character’s height.
character_controller.snap_to_ground = Some(CharacterLength::Relative(0.2));

Filtering​

It is possible to let the character controller ignore some obstacles. This is achieved by configuring the filter argument of the KinematicCharacterController::move_shape method. This QueryFilter structure is detailed in the scene query filters section.

warning

If the character-controller is used to move a collider (and the rigid-body it may be attached to) that is present in the physics scene, the filters must be used to exclude that collider (and that rigid-body) from the set of obstacles (with QueryFilter::exclude_collider and QueryFilter::exclude_rigid_body) to prevent the character from colliding with itself.

Collisions​

As the character moves along its path, it will hit grounds and obstacles before sliding or stepping on them. Knowing what collider was hit on this path, and where the hit took place, can be valuable to apply various logic (custom forces, sound effects, etc.) This is why a set of character collision events are collected during the calculation of its trajectory.

info

The character collision events are given in chronological order. For example, if, during the resolution of the character motion, the character hits an obstacle A, then slides against it, and then hits another obstacle B. The collision with A will be reported first, and the collision with B will be reported second.

let character_controller = KinematicCharacterController::default();
// Use a closure to handle or collect the collisions while
// the character is being moved.
character_controller.move_shape(
    dt,
    &query_pipeline,
    character_shape,
    character_pos,
    desired_translation,
    |collision| { /* Handle or collect the collision in this closure. */ },
);

Unless dynamic bodies are filtered-out by the character controller’s filters, they may be hit during the resolution of the character movement. If that happens, these dynamic bodies will generally not react to (i.e. not be pushed by) the character because the character controller’s offset prevents actual contacts from happening.

In these situations forces need to be applied manually to this rigid-bodies. The character controller can apply these forces for you if needed:

// First, collect all the collisions.
let mut collisions = vec![];
character_controller.move_shape(
    dt,
    &query_pipeline,
    character_shape,
    character_pos,
    desired_translation,
    |collision| collisions.push(collision),
);
// Then, let the character controller solve (and apply) the collision impulses
// to the dynamic rigid-bodies hit along its path.
// Note that we need to init a QueryPipelineMut here (because the impulse
// application will modify rigid-bodies.
let mut query_pipeline_mut = world.broad_phase.as_query_pipeline_mut(
    world.narrow_phase.query_dispatcher(),
    &mut world.bodies,
    &mut world.colliders,
    filter,
);
character_controller.solve_character_collision_impulses(
    dt,
    &mut query_pipeline_mut,
    character_shape,
    character_mass,
    &collisions,
);

Gravity​

Since you are responsible for providing the movement vector to the character controller at each frame, it is up to you to emulate gravity by adding a downward component to that movement vector.

Vehicle controller​

Simulating a car with rigid-bodies and joints, for example using one rigid-body per wheel attached to the chassis by a joint, is possible but can be difficult to control for games requiring non-realistic vehicles. This is why Rapier provides a vehicle controller (the current implementation was ported from the btRaycastVehicle of Bullet). The vehicle is a single rigid-body modeling its chassis, and its wheels are only represented by ray-casts pushing that body along a spring-like suspension.

Setup​

The chassis is created like any other dynamic rigid-body, and the wheels are added to the controller afterwards. Each wheel is given its position on the chassis, the direction of its suspension (the direction of its ray-cast), its axle, the rest length of its suspension, and its radius. The WheelTuning shared by the wheels is what makes the vehicle feel heavy or light by controlling the elastic properties (stiffness and damping) of the suspension, as well as the grip of the wheels:

// The chassis is an ordinary dynamic rigid-body.
let hw = 0.3;
let hh = 0.15;
let (chassis_handle, _) = world.insert(
    RigidBodyBuilder::dynamic().translation(Vector::new(0.0, 1.0, 0.0)),
    ColliderBuilder::cuboid(hw * 2.0, hh, hw).density(100.0),
);

// The tuning shared by the wheels: the suspension and the grip.
let tuning = WheelTuning {
    suspension_stiffness: 100.0,
    suspension_damping: 10.0,
    ..WheelTuning::default()
};

let mut vehicle = DynamicRayCastVehicleController::new(chassis_handle);
let wheel_positions = [
    Vector::new(hw * 1.5, -hh, hw),
    Vector::new(hw * 1.5, -hh, -hw),
    Vector::new(-hw * 1.5, -hh, hw),
    Vector::new(-hw * 1.5, -hh, -hw),
];

for position in wheel_positions {
    // The position of the wheel, the direction its suspension pushes along, its axle, the
    // rest length of its suspension, and its radius; all in the local frame of the chassis.
    vehicle.add_wheel(position, -Vector::Y, Vector::Z, hh, hh / 4.0, &tuning);
}

Driving the vehicle​

A vehicle is driven by giving each of its wheels an engine force, a brake force, and a steering angle. The controller is then updated before each timestep, which is when the ray-casts are made and when the resulting suspension and friction forces are applied to the chassis. It is strongly recommended to exclude the chassis from the ray-casts, otherwise the ray might hit it and be misinterpreted as being the floor.

for _ in 0..200 {
    // The vehicle is driven by setting the engine force, the brake, and the steering angle of
    // its wheels. Here the two front wheels are the driving and steering ones.
    let wheels = vehicle.wheels_mut();
    wheels[0].engine_force = 30.0;
    wheels[0].steering = 0.2;
    wheels[1].engine_force = 30.0;
    wheels[1].steering = 0.2;

    // The wheels are ray-casted against the scene: the chassis itself, as well as every other
    // dynamic body, is generally excluded from these ray-casts.
    let queries = world.broad_phase.as_query_pipeline_mut(
        world.narrow_phase.query_dispatcher(),
        &mut world.bodies,
        &mut world.colliders,
        QueryFilter::exclude_dynamic().exclude_rigid_body(chassis_handle),
    );
    vehicle.update_vehicle(world.integration_parameters.dt, queries);

    world.step();
}

println!("Vehicle speed: {}", vehicle.current_vehicle_speed);
note

The state of each wheel after an update (whether it touches the floor, the compression of its suspension, its rotation angle, etc.) is readable from the controller. This is what the rendering of the wheels can be based on since there is no actual per-wheel rigid-bodies to read their state from.

PID controller​

It is generally not recommended to move a rigid-body by setting its pose directly: teleporting it would ignore every obstacle on the way. The recommended alternative is generally to push it with a force (or an impulse) that is strong enough to reach the target. However, pushing with a single constant force/impulse will generally overshoot the target. Thus, ideally, the force or impulse should be carefully selected and updated each frame as the rigid-body gets closer to its target.

This is what a PID controller (Proportional-Integral-Derivative) is designed to calculate: given the target pose, it computes the ideal velocity change bringing the body closer to it. This is the building block of the velocity-based character controllers, but it is useful for anything that must follow a target without being teleported: a dynamic moving platform, an object held by the player, a following camera, etc.

info

The gains of the controller are what makes it reach its target quickly or smoothly. The proportional gain is applied to the position errors and is usually set to a multiple of the inverse of the timestep length (e.g. 6060 for a timestep of 1/601 / 60 seconds). The derivative gain is applied to the velocity errors and is usually set in [0,1][0, 1], where 00 means no damping and 11 means that the velocity errors are corrected within a single timestep.

The coordinate axes (linear and/or angular) controlled by the controller can be selected in order, for example, to only control the translations of a body while leaving its rotations to the simulation:

// The proportional, integral, and derivative gains of the controller, acting on the linear
// axes only: the body is pushed toward its target without its rotation being controlled.
let axes = AxesMask::LIN_X | AxesMask::LIN_Y;
let mut pid = PidController::new(60.0, 0.0, 0.8, axes);
let target = Vector::new(3.0, 2.0);

for _ in 0..200 {
    let dt = world.integration_parameters.dt;
    let body = &mut world.bodies[body_handle];
    // The correction is the velocity change bringing the body closer to its target pose.
    let correction = pid.rigid_body_correction(
        dt,
        body,
        Pose::from_translation(target),
        RigidBodyVelocity::zero(),
    );
    let new_velocities = *body.vels() + correction;
    body.set_vels(new_velocities, true);

    world.step();
}
note

The integral part of the controller accumulates the position errors of the previous timesteps, which is what allows it to compensate a permanent perturbation (e.g. the gravity applied to a hovering body). This is also what makes its API mutable, and what has to be reset with PidController::reset_integrals whenever the controller is given a target it never had a chance to reach. The PdController is the variant without that integral part: its API is immutable, and its behavior is generally good enough for games.