VPVehicleControler #

The vehicle-equivalent of Unity's character controller. Simulates most types of vehicles.

VP Vehicle Controller

The vehicle controller exposes the settings for the center of mass, inertia, axles, steering, brakes, tires, powertrain (engine, clutch, gearbox, retarder, driveline), driving aids and safety aids. Other settings for the wheels (radius, mass) and suspension (spring, damper) are configured at each VP Wheel Collider component independently.

This is the block layout of an AWD vehicle in VPVehicleController:

graph RL subgraph VP Vehicle Controller subgraph Front Axle WFL>Wheel Front Left] WFR>Wheel Front Right] end subgraph Rear Axle WRL>Wheel Rear Left] WRR>Wheel Rear Right] end Eng(Engine
+
Clutch) Gear[Gearbox] Ret[Retarder
Brake] subgraph Driveline Diff0[Center Differential
or
Torque Splitter] Diff1{Axle
Differential} Diff2{Axle
Differential} end Eng-->Gear Gear-->Ret Ret-->Diff0 Diff0-->Diff1 Diff0-->Diff2 Diff1-->WFL Diff1-->WFR Diff2-->WRL Diff2-->WRR end

Notes:

You can write your own custom vehicle controller for special types of vehicles not directly covered by the stock Vehicle Controller component.

Center of mass #

Transform to be used as Center of Mass (CoM). If not specified, CoM will be calculated out of the vehicle's colliders (not recommended).

The longitudinal position of the center of mass greatly affects the behavior and handling of the vehicle. The vertical position affects the stability.

How to configure the Center of Mass

  1. Create an empty child GameObject in your vehicle (AltShiftN), name it CoM.
  2. Set it as Center of Mass in the vehicle controller.
  3. Move the CoM gameobject to the middle of your vehicle as seen from the top.
  4. Figure out the chassis of the vehicle. Change the vertical position (Y) of the CoM until it "touches" the imaginary chassis from upside.
  5. Move the CoM longitudinally (Z) slightly towards the position of the engine. It should be placed around 2/3 of the length of the vehicle.

You may modify the position of the CoM in runtime for finding a better value.

Inertia #

The inertia defines the distribution of mas along the vehicle. Inertia plays a critical role in the handling (understeer / oversteer).

How to configure the Inertia

Recommended method:

  1. In the Inertia settings choose the "Parametric" mode.
  2. Configure the chassis dimensions to roughly match the bottom part of the vehicle.
  3. Configure Inertia Bias to 1 if the vehicle has the engine in the front, or to -1 if the engine in the rear.
  4. Refine the Inertia Bias value based on the vehicle's behavior. Positive values cause more oversteer, while negative values cause more understeer.

Feel free to play with the vehicle and modify Inertia Bias in runtime for adjusting the handling.

Details: Inertia helper

Axles #

Each axle references the left-right wheels (VPWheelCollider components) and configure its features.

VP Vehicle Controller axles

Left-right wheels #

The VPWheelCollider component for each wheel of the axle. Radius, mass, suspension distance, suspension spring, suspension damper and visual meshes are configured at the VPWheelCollider.

Brakes #

Which brake system (front, rear, neutral, none) will control the brakes for this axle.

Steering #

Steering settings for this axle:

Steering #

Steering parameters for the vehicle: angle, Ackerman, toe...

VP Vehicle Controller steering

Details: Steering helper

Brakes #

Brake parameters for the vehicle, including brake power, brake balance and handbrake.

VP Vehicle Controller brakes

Details: Brakes helper

Tires #

Tire friction model and settings for the wheels of the vehicle.

VP Vehicle Controller tires

Details: Tire friction

Driveline and differential(s) #

Configures the driven axles and the elements that connect them with the drive torque upstream.

VP Vehicle Controller driveline

The driveline settings can define up to 4 driven axles connected in a variety of ways using differentials in several configurations (open, locked) and torque splitters. Each configuration is briefly described in the Editor.

Depending on the chosen configuration, different additional parts will be available for setting up:

Differential or Axle Differential
Differentials connecting two wheels of the same axle.

VP Vehicle Controller differential

Inter-axle Differential
Differentials connecting two axle differentials together before routing the connection upstream to a center differential or torque splitter. Used in 4-driven axles configurations.
Center Differential
Differential connecting two axles or groups (inter-axle or axle differentials) before routing the connection upstream to the drive torque. Used in 2, 3 and 4-driven axles configurations.
Torque Splitter
A device that provides dynamic torque routing among two outputs.

VP Vehicle Controller torque splitter

Details:

Engine #

Set up the engine of the vehicle.

VP Vehicle Controller engine

Feel free to play with these values while monitoring the resulting engine performance data in the graph and below it. If the combination of values is not correct a warning will be displayed.

Details: Engine block

Clutch #

The clutch couples the engine with the transmission and driveline.

VP Vehicle Controller clutch

Details: Clutch block

Gearbox #

Transmission type, gear ratios and transmission settings.

VP Vehicle Controller gearbox

Automatic transmissions are different than manual with auto-shift. An automatic transmission provides smooth transitions without neutral gap among gears.

Details: Gearbox block

Retarder Brake #

Retarder brake based on angular velocity. The retarder brake is commonly used in trucks, buses and heavy vehicles.

VP Vehicle Controller retarder

Details: Retarder block

Advanced / Experimental settings #

More settings are detailed at the VehicleBase reference.

Engine reaction factor #

Ratio of the reaction torque used at the engine torque calculations.

Reducing this ratio solves the low-frequency numerical resonances among wheels and engine that may occur at high-torque situations (i.e. heavy vehicles in slow gears). It should always be 1.0 unless this effect is clearly noticed.

Scripting Reference #

namespace VehiclePhysics
{
    public class VPVehicleController : VehicleBase
}

Classes #

public class VPAxle
    {
    public VPWheelCollider leftWheel;
    public VPWheelCollider rightWheel;

    public Brakes.BrakeCircuit brakeCircuit = Brakes.BrakeCircuit.Neutral;
    public Steering.SteeringMode steeringMode = Steering.SteeringMode.Disabled;
    public float steeringRatio = 1.0f;
    };

Properties #

    // Axles and driveline setup

    public VPAxle[] axles;
    public Driveline.Settings driveline = new Driveline.Settings();

    public Differential.Settings differential = new Differential.Settings();
    public Differential.Settings centerDifferential = new Differential.Settings();
    public Differential.Settings interAxleDifferential = new Differential.Settings();
    public TorqueSplitter.Settings torqueSplitter = new TorqueSplitter.Settings();

    // Steering, brakes, tire friction

    public Steering.Settings steering = new Steering.Settings();
    public Brakes.Settings brakes = new Brakes.Settings();
    public TireFriction tireFriction = new TireFriction();

    // Powertrain

    public Engine.Settings engine = new Engine.Settings();
    public Engine.ClutchSettings clutch = new Engine.ClutchSettings();
    public Gearbox.Settings gearbox = new Gearbox.Settings();
    public Retarder.Settings retarder = new Retarder.Settings();

    // Driving aids

    public SteeringAids.Settings steeringAids = new SteeringAids.Settings();
    public SpeedControl.Settings speedControl = new SpeedControl.Settings();

    // Safety aids

    public Brakes.AbsSettings antiLock = new Brakes.AbsSettings();
    public TractionControl.Settings tractionControl = new TractionControl.Settings();
    public StabilityControl.Settings stabilityControl = new StabilityControl.Settings();
    public AntiSpin.Settings antiSpin = new AntiSpin.Settings();

    // Advanced: proportion of the reaction torque used at specific calculations:
    //  - engine torque
    //  - park mode torque
    // Mitigates or removes numerical resonances at high-torque situations (i.e. heavy vehicles
    // in slow gears or Park mode).

    [Range (0, 1)]
    public float engineReactionFactor = 1.0f;
    [Range (0, 1)]
    public float parkModeReactionFactor = 0.95f;

Methods #

    // Lively compute the optimal gear shift point
    //
    // Returns:
    //
    //      > 1.0       Should upshift
    //      < -1.0      Should downshift
    //
    // Values approach 1.0 or -1.0 from 0 when the optimal shift point is being reached.
    // For example, a colored signal may change color at 0.90, 0.95 and 1.0.
    //
    // The value is the ratio between the acceleration with the next gear and the acceleration with
    // the current gear:
    //
    //      - Above 1 means more acceleration if switching one gear up.
    //        Value is the % of acceleration that would be gained (e.g. 1.05 = +5% on upshift)
    //      - Below -1 means more acceleration if switching one gear down.
    //        Value is minus the % of acceleration that would be gained (e.g. -1.05 = +5% on downshift)

    public float GetOptimalGearShiftRatio ()

    // Get the driveline and gearbox ratios along the transmission for a given wheel.
    //
    // Returns NAN if there's no direct connection between the wheel and the powertrain,
    // for example:
    //  - No drive wheel
    //  - Neutral gear
    //
    // Use VehicleBase.GetWheelIndex for retrieving wheel indexes based on axle and position.

    public float GetWheelFinalRatio (int wheelIndex, int gear = 0)

See also #

AntiSpin
Brakes
Driveline
Differential
Engine
Gearbox
Inertia
Retarder
SpeedControl
StabilityControl
Steering
SteeringAids
TireFriction
TorqueSplitter
TractionControl
VehicleBase
VPWheelCollider