Namespace NWH.WheelController3D

Classes

BumpStop

Progressive spring + damping force near suspension travel limits. Resists bottoming (compression) and over-extension (droop) past per-side activation thresholds.

Provides programmatic access to UnityEngine.InputSystem.InputActionAsset, UnityEngine.InputSystem.InputActionMap, UnityEngine.InputSystem.InputAction and UnityEngine.InputSystem.InputControlScheme instances defined in asset "Packages/com.nwh.wheelcontroller/Runtime/Input/CarInputActions.inputactions".

Damper

Suspension damper (shock absorber) controlling spring oscillation. Uses dual-slope damping: slow speeds for body control (cornering), fast speeds for bump absorption. Bump = compression (wheel up), Rebound = extension (wheel down). Start rates at 5-20% of spring maxForce. Bump typically equals or slightly less than rebound.

FrictionBase

Abstract base class for tire friction implementations in WheelController3D. Handles conversion of wheel slip conditions into tire forces that drive vehicle dynamics. Friction models translate slip velocities and tire loads into forces that affect vehicle movement.

GroundDetectionBase

Abstract base class for wheel ground detection implementations in WheelController3D. Responsible for performing collision detection between wheels and ground surfaces.

MathUtility

Collection of optimized math utility functions for WheelController3D. Provides garbage-free matrix and quaternion operations to minimize allocations in the physics loop. All methods use aggressive inlining for maximum performance.

Spring

Suspension spring with configurable force and compression characteristics. Force = MaxForce * Compression^Progressiveness. Set progressiveness to 1.0 for linear springs,

1.0 for progressive (stiffer when compressed), <1.0 for digressive (softer when compressed). MaxForce should support ~3x static wheel load with spring resting at ~30% compression.

StandardFriction

Default friction implementation using Pacejka-based curves for tire force calculations. Uses a semi-implicit Newton-Raphson solver for stable equilibrium convergence in 2-3 iterations. Includes static friction anchoring with critical damping for low-speed stability.

StandardGroundDetection

Default ground detection implementation using immediate synchronous sphere casts. Provides accurate 3D collision detection across the wheel's surface with same-frame results for maximum accuracy at high speeds.

TyreWear

Simulates tire wear by progressively reducing grip based on slip and load over time. Integrates with StandardFriction to create a dynamic grip degradation system for endurance racing or long gameplay sessions.

Wheel

Represents the physical wheel and tire assembly with all related properties. Contains both the physical characteristics (radius, width, mass) and visual references.

Key components:

Physical properties: Define wheel geometry and inertia
Visual containers: Separate rotating and non-rotating parts
Runtime state: Angular velocity, RPM, rotation angles

The wheel uses realistic physics calculations:

Inertia = mass * radius²
Angular velocity affects acceleration/braking response
Width affects contact patch and ground detection

Note: Call WheelController.Initialize() after changing physical properties.

WheelController

WheelController is a complete alternative to Unity's built-in WheelCollider, providing more realistic vehicle behavior, complete customization, and 3D ground detection across the entire bottom half of the wheel.

Key Features:

3D ground detection: The wheel has width and length, not just a single point in the middle
Fully customizable via custom inspector: Adjust spring, damper, friction curves, geometry, etc.
Pacejka friction model with support for different surfaces through FrictionPreset ScriptableObjects
Adjustable camber, caster and rim offset
Progressive suspension with customizable force curves
Multi-threaded ground detection for optimal performance (approximately 0.03ms CPU time per wheel)
Handles wheel visuals automatically (rotation and position)
Suitable for various vehicle types: cars, trucks, motorcycles, tanks, etc.

Setup Requirements:

Vehicle model should have Unity-correct rotation ([0,0,0]) and [1,1,1] scale
WheelController GameObject should be a direct child of the vehicle's Rigidbody
Position of the WheelController Transform acts as the suspension origin
Visual meshes should be assigned to the Rotating and NonRotating containers

Performance Considerations:

Ground detection occurs over the entire bottom half of the wheel, but not the top
Collisions on the top half are handled by a native MeshCollider
For best results, Time.fixedDeltaTime should be 0.01 (100Hz) or lower
On mobile platforms, no higher than 0.02 (50Hz) is recommended

WheelController.StabilityControlSettings

Per-wheel stability control settings for ABS and TCS. These features are integrated directly into the friction calculation for optimal response. Can be coordinated by higher-level modules (ABSModule, TCSModule) or set directly.

WheelControllerGroup

Groups wheels belonging to the same Rigidbody for coordinated physics updates. Handles force accumulation and state integration during substepping.

WheelControllerManager

Centralized physics manager for high-frequency wheel substepping. Runs N substeps per FixedUpdate to improve wheel physics stability.

WheelControllerState

Cached Rigidbody state for physics substepping. Allows wheel physics to run at higher frequency than Unity's native physics rate.

WheelControllerUtility

Utility class providing helper methods for WheelController3D operations and mesh generation. Contains functions for procedural mesh creation and wheel-related calculations.

Structs

ARBPair

Represents a paired set of wheels for anti-roll bar calculation. Wheels are automatically paired by similar Z (fore-aft) and opposite X (left-right) positions.

CarInputActions.CarControlsActions

Provides access to input actions defined in input action map "CarControls".

WheelHit

Contact information for a grounded wheel - updated every physics frame. Used for friction, suspension, surface detection, and effects. Only valid when WheelController.isGrounded is true. Vectors are world space unless noted as "local".

Interfaces

CarInputActions.ICarControlsActions

Interface to implement callback methods for all input action callbacks associated with input actions defined by "CarControls" which allows adding and removing callbacks.

ISubstepCallback

Callback interface for per-substep powertrain updates. Implement this on VehicleController to receive callbacks before each wheel substep.