Troubleshooting

Step-by-step guide

Import or compilation errors

  1. Confirm that the package was installed through Package Manager and that its declared dependencies resolved.
  2. If the standalone sample is involved, import NWH Common Package > Common Base Sample and then NWH Wheel Controller 3D > Base Sample.
  3. Review the first Console error before later follow-on errors.

Do not delete package assembly definitions. See the Import Guide when a script in a custom assembly cannot resolve Wheel Controller types.

The standalone sample vehicle does not receive input

  1. Confirm that the Wheel Controller Base Sample is imported and that CarController is on the vehicle's Rigidbody root.
  2. In Edit > Project Settings > Player, confirm that Active Input Handling includes the Input System.
  3. Inspect the serialized Wheels list on CarController. Its Reset() method discovers child wheels once; later hierarchy changes are not continuously rediscovered.
  4. Confirm that each list entry has the intended Power, Steer, and Handbrake flags.

The standalone sample creates and enables its own CarInputActions wrapper. It does not use VehicleSetupWizard, InputSystemVehicleInputProvider, or the Vehicle Physics Control > Input inspector. See Input.

Input is read but the vehicle does not move

  1. Confirm that the Rigidbody is not kinematic and that motion is not frozen by constraints.
  2. Confirm that powered wheel entries receive non-zero motorTorque.
  3. Confirm that brakeTorque and handbrake input are not holding every powered wheel.
  4. Remove colliders from wheel visuals. The vehicle body needs colliders, but ground contact for a wheel is handled by WheelController.
  5. Confirm that every Wheel Controller is enabled and is a direct child of the target Rigidbody.

The vehicle jitters, jumps, floats, or flips

  1. Check model rotation using Fixing Model Rotation. The vehicle and Wheel Controller objects should use Z forward and have scale [1, 1, 1].
  2. Confirm that body colliders cover the vehicle without intersecting the ground or the wheel contact area.
  3. Match each wheel's Radius, Width, suspension origin, and Spring > Max Length to the model.
  4. Tune Spring > Max Force for the Rigidbody mass, then tune bump and rebound damping.
  5. Inspect the Rigidbody's local center of mass and inertia tensor. A high center of mass can make a vehicle unstable; use Unity's Rigidbody controls or an intentionally configured Common VariableCenterOfMass, not an arbitrary fixed inertia value copied from another vehicle.
  6. For tall vehicles, keep Suspension > Load Smoothing > Auto Calculate Load Smoothing Factor enabled on each WheelController before trying a manual Load Smoothing Factor.

The vehicle slides or creeps when it should be parked

  1. On StandardFriction, Static Friction > Enabled must be ticked and Strength above 0.
  2. Raise Advanced > Long Stiffness if the vehicle holds but visibly drifts.
  3. On a cross-slope, raise Static Friction > Unpowered Break (Trailers) toward Break Threshold. Unpowered wheels give up their hold sooner than driven ones by design, which is what lets a trailer creep first.
  4. Leave Advanced > Slip Regularization Eps at its default unless you know why you are raising it. A high value saturates lateral grip at low speed and can leave a stationary vehicle sliding sideways.

Force feedback goes dead when the vehicle slides

The self-aligning torque is built from the pneumatic and mechanical trail. Pneumatic trail collapses at the grip limit on purpose - that collapse is the understeer cue - so all the remaining weight comes from mechanical trail. The default was raised to 0.08 of wheel radius in 14.3.0, but a StandardFriction saved before that keeps its 0.04. Set Advanced > Mechanical Trail to 0.08 by hand on existing vehicles.

If the standalone sample still fails, compare it with the imported Base Sample scene, then contact the developer through email support or Discord.

Exporting the vehicle prefab for debugging

Share the vehicle prefab with the developer to help debug its configuration. The models, textures, and other assets are not required.

  1. If a prefab does not already exist, create a prefab from the vehicle by dragging it into the Project view.
  2. Right click on the prefab and select Export Package…
  3. Untick Include Dependencies and click Export…

This will result in a prefab containing only the hierarchy and the components and is adequate for debugging, with file size <1Mb. Send the prefab with the bug report, if possible.

Contacting the developer

Contact me through email support or Discord. Include the following in the report:

  • Asset version (Window > Package Manager).
  • Unity version.
  • Any screenshots, videos, etc. demonstrating the behaviour.