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.

info

The vehicle controller is only available in 3D, i.e., with bevy_rapier3d.

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 vehicle controller is the RayCastVehicleController component, added to the entity of the chassis' dynamic rigid-body. Its wheels are VehicleWheel values stored in its wheels field, and can be added, removed, or modified at any time:

// 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 hw = 0.3;
let hh = 0.15;
let wheel_positions = [
    Vec3::new(hw * 1.5, -hh, hw),
    Vec3::new(hw * 1.5, -hh, -hw),
    Vec3::new(-hw * 1.5, -hh, hw),
    Vec3::new(-hw * 1.5, -hh, -hw),
];
let wheels = wheel_positions
    .into_iter()
    .map(|position| {
        // 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.
        VehicleWheel::new(position, -Vec3::Y, Vec3::Z, hh, hh / 4.0, tuning)
    })
    .collect();

// The chassis is an ordinary dynamic rigid-body, with the vehicle controller attached to it.
commands.spawn((
    Transform::from_xyz(0.0, 1.0, 0.0),
    RigidBody::Dynamic,
    Collider::cuboid(hw * 2.0, hh, hw),
    ColliderMassProperties::Density(100.0),
    RayCastVehicleController::new(wheels),
));

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.

The controller is updated automatically by the plugin before each simulation step, and the colliders attached to the chassis are always excluded from the ray-casts. Other colliders can be excluded with the filter_flags, filter_groups, exclude_colliders, exclude_rigid_bodies, and filter_predicate fields of the RayCastVehicleController (similar to the ones of the character controller), or by inserting the ControllerIgnored component on them (or on their rigid-body). So driving the vehicle is just a matter of modifying the engine force, brake, and steering of its wheels:

fn drive_vehicle(mut vehicles: Query<&mut RayCastVehicleController>) {
    for mut vehicle in vehicles.iter_mut() {
        // 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.
        for wheel in &mut vehicle.wheels[0..2] {
            wheel.engine_force = 30.0;
            wheel.steering = 0.2;
        }

        // The colliders of the chassis are always ignored by the ray-casts of the wheels. Other
        // colliders, here the ones attached to dynamic rigid-bodies, can be ignored too.
        vehicle.filter_flags =
            QueryFilterFlags::EXCLUDE_SENSORS | QueryFilterFlags::EXCLUDE_DYNAMIC;

        // The results of the last update are written back into the component.
        println!("Vehicle speed: {}", vehicle.current_vehicle_speed);
        for wheel in &vehicle.wheels {
            println!(
                "Wheel in contact: {}, suspension length: {}",
                wheel.state.is_in_contact, wheel.state.suspension_length
            );
        }
    }
}

warning

The forces applied by the vehicle controller are computed once per update of the plugin, using the length of the last simulation timestep. So it is best used with a fixed timestep.

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.

The state of each wheel is written back by the plugin into its VehicleWheel::state field (a VehicleWheelState), and the speed of the vehicle into RayCastVehicleController::current_vehicle_speed. The VehicleWheel::local_transform method computes the transform of a wheel relative to the chassis (including its suspension length, steering, and rotation), which can be given directly to the child entity rendering that wheel.