Before going through this troubleshooting guide please check that you have the latest version of the asset.

Vehicle physics is behaving weirdly (jitter, jumping, etc.).

  • Check the model rotation as per this guide.
  • Check the model scale. The root object and WheelControllers should have a scale of [1,1,1].
  • Make sure that the mass of the vehicle is set through the VehicleController ⇒ Settings tab, instead of the Rigidbody inspector.
  • Make sure that the dimensions of the vehicle are set correctly in VehicleController ⇒ Settings and update the inertia value if any changes were made.
  • If the layers of the vehicle body colliders were changed from the default of Physics.IgnoreRaycast, untick the WheelController ⇒ Auto Setup Layer Mask and untick all the layers used for the vehicle body colliders (BoxColliders, MeshColliders, etc.). This is so the wheels do not detect the vehicle itself as ground.
  • Check that the Project Settings ⇒ Time ⇒ Fixed Delta Time is 0.02 (default) or lower.
  • Check that Wheel Controller suspension length is larger than 0.1 or so.
  • Vehicle should not be further than roughly 10,000 units from the origin. This will degrade physics quality due to the floating-point precision. Consider using floating origin for open-world games.

There is no input.

  • Check that there is a VehicleInputProvider and a SceneInputProvider script present in the scene. The full name will depend on the input method used, e.g. RewiredVehicleInputProvider or InputSystemVehicleInputProvider. Only one of each script should be present per scene.
  • Check that the vehicle is AWAKE during play mode. This can be checked through the ASLEEP or AWAKE button at the top of the VehicleController inspector.
  • Check that the vehicle is receiving input by clicking on VehicleController ⇒ Control ⇒ Input. The sliders and checkboxes there should react to user input if the vehicle is awake.

Raycasting the vehicle does not work.

WheelController (by default) sets the layer of the vehicle colliders to Physics.IgnoreRaycast to prevent the wheels from hitting the vehicle itself. This will however make raycasting the vehicle from an outside script impossible. The solution to this is to manually setup the layers and WheelController layer mask:

  • Select all the colldiers on the vehicle (BoxColliders, SphereColliders, MeshColliders, etc.) and assign a custom layer to them - e.g. VehicleLayer.
  • Untick Auto Setup Layer Mask on the WheelControllers attached to the vehicle. A layer mask dropdown will appear. Make sure to untick the VehicleLayer on that list.

WheelControllers will now ignore the vehicle itself but the vehicle will be Raycastable.

How to make the vehicle feel more arcade?

NWH Vehicle Physics 2 is by default set up more towards realism / simcade style of vehicles and tries to be as physically accurate as possible. However, sometimes games require a more arcade approach. Here are a few tweaks to get more arcade behavior:

  • Adjust Lateral Slip Coefficient of WheelController to a lower value, e.g. 0.5 or 0.7. This will reduce the tendency of the vehicle to snap oversteer and in general lose traction.
  • Adjust Longitudinal Slip Coefficient of WheelController to a lower value. This will make wheel spin less likely to happen with short bursts of torque (e.g. gear changes).
  • Adjust Slip Circle Shape of WheelController to 1. This will make wheel spin have less influence on the lateral grip, however, it will be harder to do powerslides.
  • Set the center of mass to be a bit lower than realistic, e.g. a few centimeters above the floor of the vehicle. This will reduce leaning in the corners.
  • Reduce VehicleController > Settings > Inertia to make the vehicle change direction more easily and feel more like an RC car. Overdoing it might cause instabilities and jitter.
  • For more advanced users adjusting the wheel friction curve of the friction presets can also help. However, in most cases adjusting slip coefficients will be adequate.

Vehicle bounces after falling from height.

This is caused by the suspension bottoming out which triggers de-penetration code whose main job is to prevent the wheels from going into the ground. Bottoming out is caused by either too soft suspension or suspension travel that is shorter than the distance traveled in one physics frame, resulting is suspension that goes from fully extended to fully compressed (and further) before the code has a chance to update. There are a few ways this behaviour can be fixed:

  • If the jump is small and the issue is not suspension travel, using stiffer suspension - especially bump damping - will solve the issue.
  • If possible having a collider on the underside of the vehicle that prevents the suspension from fully compressing can be a solution.
  • Spring values that can not hold the vehicle weight should be avoided. E.g. Max spring force setting of 10,000N (~1000kg) when using 4 wheels on a 10,000kg vehicle will not be enough and the vehicle will bottom out even while stationary.
  • Increasing physics update rate by reducing Time.fixedDeltaTime. Default of 50Hz is quite low for vehicle physics and 100Hz will have much better results (Settings > Time > Fixed Delta Time of 0.01).
  • If bottoming out can not be avoided there are 'Depenetration Spring' and 'Depenetration Damper' values under WheelController that can be tweaked to fit the vehicle.

How to improve mobile performance?

VehicleController is quite well optimized but the settings by default are intended for desktop devices and visual quality.
Here are a few optimization tips:

  • Lower the scan resolution on the WheelControllers otherwise.
  • Use lower values for physics update rate under VehicleController > Settings.
  • Use Project Settings > Time > Fixed Delta Time of 0.02.
  • Use vehicles with low poly meshes.
  • Use mobile particle and skidmark shaders (included with Unity).
  • Reduce particle count and avoid using Soft particles.
  • Reduce the quality of skidmarks under VehicleController > FX > Skidmark Manager.
  • Disable unneeded vehicle components under VehicleController > Settings > State Settings.
  • If there is stuttering on collision reduce the VehicleController > DamageHandler > Deformation Vertices Per Frame or use lower poly count mesh.

Why is physics update rate so important?

This is because the physics updates in discrete intervals (each X seconds, e.g. 0.02s by default) which means that the vehicle travels certain distance in between the frames, where there is no physics update. At 450 km/h, for example, that is 125 m/s or 2.5 meters traveled between the frames when using Time.fixedDeltaTime of 0.02 (50Hz physics update). In comparison, only a few cm of sideways travel on the tire can result in slip reaching the peak value and going over it, resulting in reduced friction due to the way tires work on hard surfaces in general. So, there are two ways to get around this:

  • Increase the update rate. This can be done two ways. Through Project Settings > Time > Fixed Delta Time (the most important setting but affects things globally, lower is better for quality) and through Vehicle Controller > Settings > Physics Update Rate. The first option is the actual physics rate of the engine while the second option fills in the frames in-between the Unity FixedUpdate calls using NRigidbody. So set the Fixed Delta Time to the lowest it can go for the target device (0.01 is usually adequate, but if you can go 0.005 even better) while not affecting performance.
  • Make the simulation a bit looser so that the tire can have a bit more play before 'going off the rails'. This can be done by decreasing Wheel Controller > Lateral Slip Coefficient to a value smaller than 1 (e.g. 0.6).