LOD System

Distance-based component activation for performance optimization.

Overview

LOD system checks vehicle-to-camera distance every 0.2s and enables/disables components based on StateSettings configuration.

Key Properties:

  • lodCamera - Camera for distance measurement (defaults to Camera.main)
  • activeLODIndex - Current LOD level (0 = highest detail)
  • activeLOD - Current LOD object reference
  • vehicleToCamDistance - Distance in meters
  • onLODChanged - UnityEvent fired on LOD transitions

Component LOD Behavior:

  • lodIndex = -1 - Component ignores LOD (always active when enabled)
  • lodIndex >= 0 - Component follows StateSettings LOD rules
  • Component enabled when activeLODIndex <= component.lodIndex

StateSettings Configuration

Create: Right-click > Create > NWH > Vehicle Physics 2 > State Settings

LODs List:

  • Each LOD defines a distance threshold (meters)
  • LODs must be ordered from lowest to highest distance
  • System automatically assigns the correct LOD based on camera distance

Component Definitions:

  • Auto-populated via Refresh button (scans all VehicleComponent types)
  • Per component: enable/disable state and LOD index
  • Changes apply only to vehicles enabled after modification

Example Configuration:

LOD 0: 0m    - All components active
LOD 1: 50m   - Disable particles/effects
LOD 2: 100m  - Disable sound, non-critical modules
LOD 3: 200m  - Minimal (powertrain only)

Multi-Camera Setup

For split-screen or multi-camera scenarios, assign specific camera to each vehicle's lodCamera field. Each vehicle independently tracks distance to its assigned camera.

Events

Subscribe to LOD changes for custom behavior:

vehicleController.onLODChanged.AddListener(() => {
    Debug.Log($"LOD changed to {vehicleController.activeLODIndex}");
});

Troubleshooting

LOD not updating:

  • Verify StateSettings assigned to VehicleController
  • Check StateSettings has valid LOD list
  • Ensure lodCamera is valid (or Camera.main exists)
  • Confirm LOD coroutine running (activeLODIndex != -2)

Components not responding to LOD:

  • Verify component lodIndex >= 0 (use -1 to ignore LOD)
  • Check component listed in StateSettings definitions
  • Refresh StateSettings if new components added

LOD distance validation failed:

  • LODs must be ordered from lowest to highest distance
  • Check Unity console for validation warnings from StateSettings

Best Practices

  • Use platform-specific StateSettings (desktop vs mobile)
  • Test with multiple vehicles at various distances
  • Profile to verify performance gains
  • Disable visual effects (particles, skidmarks) before physics
  • Keep player-controlled vehicle at LOD 0 for best experience
  • Combine with Rigidbody sleep for maximum optimization