Wheel Controller

WheelController is a complete alternative to Unity's WheelCollider, providing realistic vehicle physics with full customization and 3D ground detection.

Key Features

  • 3D Ground Detection: Full wheel surface contact detection, not just a single raycast point
  • Pacejka Friction Model: Industry-standard tire physics with customizable FrictionPreset ScriptableObjects
  • Multi-threaded: Approximately 0.03ms CPU time per wheel
  • Adjustable Geometry: Camber, caster, and rim offset support
  • Progressive Suspension: Customizable force curves for spring and damper
  • Integrated Stability Control: Per-wheel ABS and TCS built into friction solver
  • Substepping Support: High-frequency physics updates managed by WheelControllerManager
  • Automatic Visual Handling: Rotation and positioning of wheel meshes

Setup Requirements

Transform Hierarchy

  • Vehicle root must have [1,1,1] scale and [0,0,0] rotation
  • WheelController GameObject must be direct child of vehicle Rigidbody
  • WheelController Transform position acts as suspension pivot point
  • Assign wheel meshes to Rotating and NonRotating visual containers

Physics Configuration

  • Time.fixedDeltaTime: 0.01 (100Hz) for desktop, max 0.02 (50Hz) for mobile
  • Physics solver iterations: 12+ velocity, 8+ position recommended
  • LayerMask: Exclude vehicle colliders and triggers from ground detection

Core Components

Spring

Controls vertical suspension behavior.

Key Properties:

  • maxForce: Maximum spring force at full compression (should support ~3x static wheel load)
  • maxLength: Total suspension travel in meters (0.1-0.3m typical for cars)
  • forceCurve: Allows progressive/digressive spring rates
  • compression: Current compression ratio [0-1]

Spring should rest at ~30% compression under static load.

Damper

Resists suspension oscillation.

Key Properties:

  • bumpRate: Compression damping force
  • reboundRate: Extension damping force
  • slowBump/fastBump: Dual-slope bump damping multipliers
  • slowRebound/fastRebound: Dual-slope rebound damping multipliers

Typical values: 5-20% of spring maxForce. Enable implicitDamping to prevent oscillation at low physics rates.

FrictionPreset

ScriptableObject defining tire friction characteristics. Different presets for different surfaces (asphalt, gravel, ice).

See FrictionPreset documentation for details.

Wheel

Physical and visual properties.

Key Properties:

  • radius: Wheel radius in meters (0.3-0.5m typical)
  • width: Wheel width in meters (0.15-0.3m typical)
  • mass: Affects rotational inertia only
  • inertia: Calculated automatically from mass and radius
  • rimOffset: Scrub radius offset from wheel center
  • rotatingContainer: Transform for wheel mesh (spins)
  • nonRotatingContainer: Transform for brake caliper (static)

Load Rating

Maximum tire load in Newtons [N].

Auto-calculation (recommended):

  • autoCalculateLoadRating = true
  • Formula: (vehicleMass * gravity / wheelCount) * 2

Manual setup:

  • Should be 1.5-2x static load on wheel
  • Too low: excessive sliding
  • Too high: unrealistic friction
  • Typical: 3000-6000N cars, 10000-20000N trucks

Anti-Roll Bar (ARB)

Reduces body roll by coupling opposite wheels.

Key Properties:

  • arbStiffness: Torsional stiffness in Nm/rad (0 disables, 500-5000 typical, 10000+ race)
  • arbDamping: Damping coefficient in Nm*s/rad (5-20% of stiffness)

Wheels auto-pair by position (similar Z, opposite X).

Stability Control

Integrated ABS and TCS at friction solver level for optimal response.

ABS (Anti-lock Braking System)

stabilityControl.absEnabled = true;
stabilityControl.absSlipThreshold = 0.15f;  // Slip at which ABS starts
stabilityControl.absSlipRange = 0.15f;       // Intervention range

TCS (Traction Control System)

stabilityControl.tcsEnabled = true;
stabilityControl.tcsSlipThreshold = 0.10f;           // Slip at which TCS starts
stabilityControl.tcsMaxCounterTorqueRatio = 0.8f;    // Max counter as fraction of available
stabilityControl.tcsMaxCounterTorque = 3000f;        // Absolute max counter in Nm

Coordinate with vehicle-level ABSModule and TCSModule or set directly per wheel.

Camber

Dynamic Camber (recommended):

useCamberCurve = true;
camberCurve = AnimationCurve(
    new Keyframe(0, 0),    // At full extension
    new Keyframe(1, -3)    // At full compression
);

Static/External Camber:

useCamberCurve = false;
camber = -2.0f;  // Degrees (negative = top tilts inward)

Typical values:

  • Road cars: 0 to -3 degrees
  • Race cars: -5 to -10 degrees

Important Properties

Input (set by powertrain or user)

  • motorTorque: Drive torque in Nm (readonly in VP2 - set by powertrain)
  • brakeTorque: Brake torque in Nm (must be positive)
  • steerAngle: Steering angle in degrees

Output (read by user)

  • isGrounded: True when wheel touches ground
  • load: Current vertical tire load in N
  • frictionForce: Total friction force vector
  • frictionSlip: Longitudinal and lateral slip (X=forward, Y=side)
  • normalizedSlip: Slip normalized to [0-1]
  • counterTorque: Torque returned to powertrain
  • wheelHit: Detailed ground contact info
  • absActive: True when ABS is actively reducing brake
  • tcsActive: True when TCS is actively applying counter-torque

Force Feedback

  • aligningMoment: Self-aligning torque (Mz) in Nm for steering FFB
  • tireScrub: Tire sliding intensity [0-1] for FFB vibration

Public Methods

Initialize()

Reinitialize after configuration changes:

  • Changing wheel radius, width, or mass
  • Moving WheelController transform
  • Changing parent Rigidbody
  • Adding/removing vehicle colliders

Called automatically on Start(), can be called manually for runtime changes.

Step(deltaTime, vehicleMatrix)

Main physics update. Called by WheelControllerManager or Powertrain. Performs ground detection, calculates forces, updates wheel state.

SubStep(substepDt, rbState, group)

Single physics substep using cached rigidbody state. Called by WheelControllerManager during substepping for higher accuracy.

PositionToVisual()

Auto-position WheelController transform above wheel visual based on:

  • Spring settings and expected compression
  • Vehicle mass and static load distribution

Useful during initial setup.

FindOrSpawnVisualContainers()

Locates or creates required child containers:

  • "Rotating": Wheel mesh and parts that spin
  • "NonRotating": Brake calipers, suspension arms

Called automatically during initialization.

Performance

Ground Detection

  • Occurs over bottom half of wheel only
  • Top half handled by native MeshCollider
  • Multi-threaded: ~0.03ms per wheel
  • Static friction optimization: Skips subsequent substep casts when wheel anchored

Contact Modification

useContactModification = true (default) softens forward collisions to smooth curb/obstacle impacts.

Other Body Forces

otherBodyForceScale scales forces applied to hit Rigidbodies:

  • 0: No forces on other objects
  • 0.1-0.5: Arcade games (prevents launch)
  • 0.5-1.0: Simulations

Advanced Settings

Rolling Resistance

rollingResistanceTorque = 30f;  // Nm (10-30 cars, 50-200 trucks)

Constant resistance simulating tire deformation and bearing friction.

Contact Velocity Smoothing

Load smoothing (60% new, 40% old) prevents oscillation propagation to friction. Compression velocity smoothing (70% new, 30% old) reduces noise at 50Hz physics.

Implicit Damping

implicitDamping = true;  // Recommended: always on

Prevents jitter at 40-50Hz physics rates by scaling damper forces.

Telemetry

Properties marked with [ShowInTelemetry] are available for debugging:

  • Use WheelTelemetryRecorder (MCP tool) for automated recording
  • Capture load, slip, forces, RPM over time
  • Analyze friction behavior and suspension performance

Common Issues

Vehicle Slides Excessively

  • Increase loadRating (should be 1.5-2x static load)
  • Check FrictionPreset stiffness values
  • Verify spring maxForce supports vehicle weight

Suspension Bottoms Out

  • Increase spring.maxForce (should be 3x static load minimum)
  • Increase spring.maxLength for more travel
  • Check that spring rests at ~30% compression

Wheel Jitter/Oscillation

  • Enable implicitDamping
  • Increase damper rates
  • Lower physics timestep (Time.fixedDeltaTime)
  • Check for singular transform matrices (scale issues)

Wheels Clip Through Obstacles

  • Disable useContactModification or tune gradient
  • Increase meshCollider layer collision detection
  • Verify layerMask excludes only vehicle colliders

See Also