Vehicle Controller

VehicleController inspector

Main controller component that coordinates all vehicle systems. Attach this to your vehicle's root GameObject.

Architecture

Component-based system where each subsystem (powertrain, effects, sound, etc.) can be enabled/disabled independently. Uses StateSettings for LOD configuration.

Core Systems

Powertrain

Engine, clutch, transmission, differentials, and wheels. See Powertrain.

Control

Steering, brakes, and input handling.

Effects & Sound

Skidmarks, particles, lights, exhaust effects, and audio system.

Modules

Optional systems: ABS, TCS, ESC, Aerodynamics, Fuel, NOS, Trailer, etc. See ModuleManager.

Requirements

  • Rigidbody (added automatically)
  • WheelController 3D components on child objects

Physics Settings

Fixed Timestep: 0.01667 (60Hz) desktop, 0.02-0.03 mobile Solver: TGS recommended Rigidbody:

  • Mass: 1000-2000 kg (cars), 3000-10000 kg (trucks)
  • Drag: 0
  • Angular Drag: 0.05
  • Interpolation: Interpolate

Properties

Dimensions

Property Description
dimensions Vehicle size (Width × Height × Length) in meters. Affects inertia calculations
dimensionsGizmoOffset Offset for dimension gizmo visualization
wheelbase Distance between front and rear axles (auto-calculated for 4-wheel vehicles)

World Positions

Property Description
WorldEnginePosition Engine position in world space for audio/effects
WorldExhaustPosition Exhaust position in world space for particles/sound
WorldTransmissionPosition Transmission position in world space for audio

Slip Thresholds

Property Description
lateralSlipThreshold Lateral slip threshold for effects/sound only (default: 0.15)
longitudinalSlipThreshold Longitudinal slip threshold for effects/sound only (default: 0.3)

LOD

Property Description
multiplayerInstanceType "Local" for player vehicle, "Remote" for others
lodCamera Camera for LOD distance checks (uses Camera.main if null)

Cached Values

Property Description
deltaTime Cached Time.deltaTime (updated per frame)
fixedDeltaTime Cached Time.fixedDeltaTime (updated per FixedUpdate)
realtimeSinceStartup Cached Time.realtimeSinceStartup

State System

StateSettings ScriptableObject controls which components are active at each LOD level. See State Settings and LOD.

Update Order

Each frame:

  1. Update() - Input, state updates
  2. FixedUpdate() - Ground detection → Input → Powertrain → Steering → Brakes → Modules → Effects
  3. LateUpdate() - Visual updates (wheel models)

Component Lifecycle

All components inherit from VehicleComponent:

  • VC_Initialize() - Setup
  • VC_SetDefaults() - Default config
  • VC_Validate() - Validation
  • VC_Enable() / VC_Disable() - State changes
  • VC_Update() / VC_FixedUpdate() - Updates

Public Methods

Initialization

  • IsInitialized - Returns true after vehicle and all components are fully initialized. Always check this before accessing components from external scripts
  • SetDefaults() - Resets vehicle to default configuration. Loads default assets from Resources

Ground Detection

  • IsGrounded() - Returns true if any wheel is grounded
  • IsFullyGrounded() - Returns true if all wheels are grounded

Friction Control

  • BreakStaticFriction() - Forces all grounded wheels to exit static friction mode

Validation

  • Validate() - Performs full setup validation. Reports issues to Console. Editor-only

Components Access

  • Components - List of all VehicleComponents (Input, Sound, Modules, Steering, Powertrain, Effects, Brakes, GroundDetection)

Events

  • onVehicleInitialized - Invoked after all components have been initialized
  • onLODChanged - LOD level changed
  • onWake / onSleep - Rigidbody state
  • onEnable / onDisable - Component state

Setup

Use Tools > NWH > Vehicle Physics 2 > Vehicle Setup Wizard for automatic configuration, or see Quick Start Guide.

Performance

  • LOD system for distant vehicles
  • Component pooling for effects/sounds
  • Disable unused modules
  • Increase Fixed Timestep on mobile (0.02-0.03)

Common Issues

Unstable physics: Lower Fixed Timestep, check center of mass, verify wheel/suspension settings

Poor performance: Enable LOD, reduce modules, check Fixed Timestep

No input: Check Input Provider assignment, verify vehicle is awake

See FAQ for more.