Quick Start

This guide covers setting up Wheel Controller 3D for wheel simulation with realistic suspension and friction physics.

Info: Wheel Controller 3D can be used standalone with the included CarController, or as part of NWH Vehicle Physics. If you're setting up a full vehicle with NWH Vehicle Physics, see the Vehicle Physics Quick Start instead.

Samples can be imported from the Samples tab in the Package Manager under In Project (left sidebar) > Wheel Controller 3D > Samples

Model Requirements

Warning: Ensure your vehicle model has Unity-correct rotation and pivot points. The model should use Z - Forward, Y - Up, and X - Right axes. If your model has incorrect rotation and/or pivot points, consult this Fixing Model Rotation guide.

Warning: Maintain a vehicle scale of [1,1,1]. Adjust the vehicle scale using the model import settings in Unity or 3D software prior to setup.

Physics Settings

  • For PC games, it is recommended to change the Fixed Timestep (Edit > Project Settings > Time) from the default 0.02 (50Hz) to 0.01667 (60Hz), 0.01 (100Hz), or even 0.00833 (120Hz) for smoother physics behavior. For mobile devices, set this value between 0.02 and a maximum of 0.03 (33Hz), but note that this may result in lower physics quality.
  • All NWH assets use only SI units (kg, m, N, etc.).

Automatic Setup

The fastest way to set up wheels is using the automated wizard:

  1. Add your vehicle model to the scene with correct rotation and scale [1,1,1]
  2. Add a Rigidbody to the vehicle root and set the mass (e.g., 1400 for a car)
  3. Add a Collider to the vehicle (the Rigidbody requires this to function)
  4. Attach WheelControllerSetupWizard to the vehicle root
  5. Assign your wheel meshes to the wizard's wheel slots
  6. Click Auto-Setup and follow the console output
  7. For standalone use, add the CarController component to control the vehicle

The wizard will automatically create WheelController objects, position them correctly, and configure basic settings.

Manual Setup

Step 1: Rigidbody and Collider

  1. Add a Rigidbody component to the vehicle root object
  2. Set the mass to a reasonable value (e.g., 1400 for a standard car)
  3. Add a Collider (BoxCollider, MeshCollider, etc.) to the vehicle body

Step 2: Create WheelController Objects

WheelController components must be attached to GameObjects positioned at the suspension anchor points (where the spring begins), not on the wheel meshes themselves.

  1. Create an empty GameObject for each wheel (or duplicate your wheel meshes and remove all components except Transform)
  2. Position these objects above the wheel center - this position represents the top of the suspension travel
  3. The easiest approach: duplicate your wheel meshes, name them "WheelController_FL", "WheelController_FR", etc., remove all components except Transform, and move them up slightly

Vehicle hierarchy with WheelControllers and positioning of front left WheelController on the example vehicle

Step 3: Add WheelController Components

  1. Attach a WheelController component to each GameObject created in Step 2
  2. The component will automatically:
    • Set Target Rigidbody to the vehicle's Rigidbody
    • Create child containers: Rotating and NonRotating
    • Initialize with default values
  3. Verify the Target Rigidbody field is correctly assigned

Step 4: Parent Wheel Meshes

  1. For each WheelController, parent your visual wheel mesh to the automatically created Rotating container child
  2. If you have brake calipers or other non-rotating parts, parent them to the NonRotating container
  3. Ensure wheel meshes have Unity-correct rotation (Z-forward) and centered pivots

Wheel mesh parented to Rotating container

Step 5: Configure Wheel Dimensions

  1. Enable Gizmos (top-right of Scene view)
  2. Select each WheelController - you'll see wheel and suspension gizmos
  3. Adjust Radius and Width until the cyan wheel gizmo matches your wheel mesh

Wheel gizmo. The vertical 'I' represents the suspension travel while the cylinder represents the wheel.

Step 6: Adjust Suspension

  1. Press Play - the vehicle suspension should now be functional
  2. If the ride height is too high/low:
    • Don't change Spring > Max Length (unless you need more travel)
    • Do move the WheelController GameObject up (to lower ride height) or down (to raise it)
    • The white "I" gizmo shows the full suspension travel range
  3. Adjust Spring > Max Force so the suspension rests at ~30% compression (check Debug tab in play mode)

Adjusting ride height by moving WheelController position

Step 7: Add Vehicle Control (Standalone Only)

If using WheelController without NWH Vehicle Physics:

  1. Add the CarController component to your vehicle root
  2. The wheels will be found automatically
  3. Configure which wheels steer, are powered, and use handbrake:
    • Steer: Enable for front wheels (or all for 4-wheel steering)
    • Powered: Enable for driven wheels (front for FWD, rear for RWD, all for AWD)
    • Handbrake: Enable for rear wheels typically
  4. Configure input (the CarController uses Unity's Input Manager by default)

Info: If using WheelController as part of NWH Vehicle Physics, skip CarController and add VehicleController instead. See Vehicle Physics documentation.

Fine-Tuning

Suspension Tuning

For detailed suspension setup, see WheelController Setup. Key adjustments:

  • Spring Max Force: Adjust so suspension rests at 20-40% compression
  • Damper Bump/Rebound: Control suspension stiffness (start with 5-20% of Max Force)
  • Spring Progressiveness: 1.0 = linear, <1.0 = softer when compressed, >1.0 = stiffer when compressed

Friction Presets

WheelController uses FrictionPreset ScriptableObjects for tire behavior:

  1. The default preset is suitable for dry asphalt
  2. To create custom presets: Right-click in Project > Create > NWH > WheelController3D > Friction Preset
  3. Adjust Pacejka BCDE parameters to tune tire grip characteristics
  4. Assign different presets to different wheels (e.g., lower grip on rear for oversteer)

For details, see FrictionPreset documentation.

Center of Mass

If the collider is small or offset, use VariableCenterOfMass to adjust vehicle balance:

  1. Add VariableCenterOfMass to the vehicle root
  2. Lower the center of mass (Y value) to reduce body roll
  3. Move forward/backward (Z value) to adjust understeer/oversteer balance
  4. Target inertia for typical cars: [700, 1400, 400] or higher

Info: For Unity 2023 and newer, you can adjust center of mass and inertia directly on the Rigidbody component.

Troubleshooting

  • Vehicle jitters or jumps: Check that Rigidbody has reasonable mass (800-2000 for cars) and at least one Collider is present
  • Wheels sink into ground: Move WheelController objects upward to increase ride height
  • Suspension bottoms out: Increase Spring > Max Force or use longer Spring > Max Length
  • Vehicle feels floaty: Increase damper values (Bump and Rebound rates)
  • Wheels don't rotate: Ensure wheel meshes are parented to the Rotating container, not directly to WheelController

For more troubleshooting, see the WheelController Setup page.

Assembly Definitions

This asset uses Assembly Definition (.asmdef) files. There are many benefits to assembly definitions but a downside is that the whole project needs to use them or they should not be used at all.

  • If the project already uses assembly definitions, add a reference to NWH.WheelController3D in your project's .asmdef file
  • If the project does not use assembly definitions, simply remove all the .asmdef files from the asset after import

Next Steps