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 the r3 functions.

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 R3WheelTuning 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 R3DynamicRayCastVehicleController object, created by r3NewDynamicRayCastVehicleController from the handle of the chassis' dynamic rigid-body. It remembers the world of that rigid-body, so it must be freed with r3FreeDynamicRayCastVehicleController before that world is freed. The wheels are added with r3DynamicRayCastVehicleController_AddWheel, which returns the index of the new wheel (starting from zero, in insertion order), and the R3WheelTuning given to each wheel is initialized with r3DefaultWheelTuning:

// The chassis is an ordinary dynamic rigid-body.
const R3Real hw = 0.3;
const R3Real hh = 0.15;
R3RigidBodyDesc chassis_body = r3DynamicRigidBodyDesc();
chassis_body.position.translation = r3Vector(0.0, 1.0, 0.0);
R3RigidBodyHandle chassis_handle = r3InsertRigidBody(world, &chassis_body);
R3ColliderDesc chassis_collider = r3CuboidColliderDesc(r3Vector(hw * 2.0, hh, hw));
chassis_collider.density = 100.0;
r3InsertCollider(chassis_handle, &chassis_collider);

// The tuning shared by the wheels: the suspension and the grip.
R3WheelTuning tuning = r3DefaultWheelTuning();
tuning.suspension_stiffness = 100.0;
tuning.suspension_damping = 10.0;

// The controller must be freed (with r3FreeDynamicRayCastVehicleController) before its world.
R3DynamicRayCastVehicleController *vehicle = r3NewDynamicRayCastVehicleController(chassis_handle);
const R3Vector wheel_positions[4] = {
    {hw * 1.5, -hh, hw},
    {hw * 1.5, -hh, -hw},
    {-hw * 1.5, -hh, hw},
    {-hw * 1.5, -hh, -hw},
};

for (size_t i = 0; i < 4; i++) {
    // 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.
    r3DynamicRayCastVehicleController_AddWheel(vehicle, wheel_positions[i], r3Vector(0.0, -1.0, 0.0),
                                               r3Vector(0.0, 0.0, 1.0), hh, hh / 4.0, &tuning);
}

By default, the vehicle moves forward along the local x axis of the chassis, and its local y axis points upward. Other axes can be selected with r3DynamicRayCastVehicleController_SetAxes.

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 engine force, brake, and steering angle of a wheel are set with r3DynamicRayCastVehicleController_SetWheelControls (from the index of the wheel), and the controller is updated with r3DynamicRayCastVehicleController_UpdateVehicle before each r3Step. The colliders attached to the chassis are always excluded from the ray-casts, and the other obstacles can be filtered with the R3QueryOptions given to the update (see the scene query filters). Note that its predicate callback, if any, is called once for every collider of the world before the update, while the world is locked for writing: it may only use the Read functions of its R3ReadContext.

// The wheels are ray-casted against the scene: the chassis itself is always excluded, and
// every other dynamic body is generally excluded from these ray-casts too.
R3QueryOptions options = r3DefaultQueryOptions();
options.filter.flags = R3_QUERY_EXCLUDE_DYNAMIC;

for (int i = 0; i < 200; i++) {
    // The vehicle is driven by setting the steering angle, the engine force, and the brake of
    // its wheels. Here the two front wheels (indices 0 and 1) are the driving and steering ones.
    r3DynamicRayCastVehicleController_SetWheelControls(vehicle, 0, 0.2, 30.0, 0.0);
    r3DynamicRayCastVehicleController_SetWheelControls(vehicle, 1, 0.2, 30.0, 0.0);

    r3DynamicRayCastVehicleController_UpdateVehicle(vehicle, r3TimeStep(world), &options);

    r3Step(world, NULL, NULL);
}

printf("Vehicle speed: %f\n", (double)r3DynamicRayCastVehicleController_CurrentVehicleSpeed(vehicle));

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 the wheels is copied into a buffer of R3WheelState by r3DynamicRayCastVehicleController_Wheels: the world-space center of each wheel, the world-space directions of its suspension and axle, its rotation angle, the length and force of its suspension, and its contact with the ground (whether it touches it, the collider touched, and the world-space contact point and normal). The speed of the vehicle along its forward axis is given by r3DynamicRayCastVehicleController_CurrentVehicleSpeed.

// The wheels are given in the order they were added to the controller.
R3WheelState wheels[4];
size_t num_wheels = r3DynamicRayCastVehicleController_Wheels(vehicle, wheels, 4);
for (size_t i = 0; i < num_wheels; i++) {
    // The world-space center of the wheel, its current suspension length, rotation angle, etc.
    printf("Wheel %zu: center (%f, %f, %f), suspension length %f, rotation %f, in contact: %u\n", i,
           (double)wheels[i].center.x, (double)wheels[i].center.y, (double)wheels[i].center.z,
           (double)wheels[i].suspension_length, (double)wheels[i].rotation,
           (unsigned)wheels[i].is_in_contact);
}