Vehicle State Settings

ScriptableObject defining vehicle behavior profiles, primarily for LOD system configuration.

Purpose

  • LOD configuration (which components active at each distance)
  • Performance profiles (Desktop/Mobile/Console)
  • Quality presets (High/Medium/Low)

Creation

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

Name appropriately: DesktopStateSettings, MobileStateSettings, etc.

Assignment

  • Per vehicle: VehicleController inspector > State Settings field
  • Default: Loads from Resources if not assigned
  • Runtime: Can swap via code

Structure

StateSettings contains:

  • LODs: List of LOD distance thresholds (ordered ascending)
  • definitions: List of StateDefinitions for all VehicleComponent types

Each StateDefinition has:

  • fullName: Component type (e.g., "NWH.VehiclePhysics2.Sound.SoundManager")
  • isEnabled: Whether component is enabled
  • lodIndex: -1 = always active, 0+ = LOD threshold
  • initialized: Tracks initialization state

Each LOD has:

  • distance: Distance threshold in meters

Configuration

LOD Levels

LODs must be ordered from lowest to highest distance:

LOD 0: 40m (close range)
LOD 1: 120m (medium range)
LOD 2: 300m (far range)

StateSettings validates order on save. Incorrect ordering causes warnings.

Component States

Component behavior per LOD:

  • Enabled: VC_Update() and VC_FixedUpdate() called
  • Disabled: No updates, zero processing

Component lodIndex:

  • -1: Ignores LOD system, always active when enabled
  • 0: Active when activeLODIndex >= 0
  • 1: Active when activeLODIndex >= 1
  • Higher values progressively restrict to farther LODs

Platform Profiles

Create separate StateSettings per platform:



#if UNITY_STANDALONE
    vc.stateSettings = desktopSettings;


#elif UNITY_MOBILE
    vc.stateSettings = mobileSettings;


#endif

Desktop Example

LOD 0 (0-40m): Full LOD 1 (40-120m): Skidmarks + core sounds LOD 2 (120m+): Minimal

Mobile Example

LOD 0 (0-25m): Reduced effects LOD 1 (25-75m): Core only LOD 2 (75m+): Minimal

Runtime Management

Swap settings:

vc.stateSettings = lowQualitySettings;

Dynamic quality adjustment:

if (averageFPS < 30) {
    foreach (var vehicle in vehicles) {
        vehicle.stateSettings = lowQualitySettings;
    }
}

Refresh component definitions after adding new VehicleComponent types:

stateSettings.Reload();

Best Practices

  • Test each LOD level
  • Platform-specific profiles
  • Start conservative, optimize based on profiling
  • Keep critical components (Input, core physics) at lodIndex = -1
  • Disable effects before physics at higher LODs
  • Version control StateSettings assets
  • Share common settings across vehicles

API Reference

StateSettings

Reload() - Scans assemblies for VehicleComponent types, adds new definitions, removes obsolete ones. Call after adding custom components.

GetDefinition(string fullComponentTypeName) - Retrieves StateDefinition for a component type. Returns null if not found.

ValidateLODOrder() - Checks LOD distances are in ascending order. Returns true if valid, logs warning if not.

LODCount - Number of LOD levels (cached).

VehicleController LOD

activeLODIndex - Current LOD index. -2 = initialization failed, 0 = highest detail, higher = lower detail.

activeLOD - Current LOD instance with distance and name.

vehicleToCamDistance - Distance to camera in meters (updated every 0.2s).

lodCamera - Camera for distance calculations. Null uses Camera.main.

onLODChanged - UnityEvent invoked when LOD changes.

Troubleshooting

Components not disabling: Check lodIndex ≥ 0, verify StateSettings assigned, press Refresh button in StateSettings to update component list

No performance gain: Profile to verify components actually disable, check LOD distances use ascending order

Unexpected behavior: Verify correct StateSettings assigned, check activeLODIndex in inspector during play mode

Integration

StateSettings is the backbone of the LOD system. See LOD System.

Flow:

  1. VehicleController measures distance to camera
  2. Active LOD determined by distance vs StateSettings thresholds
  3. Component states read from StateSettings
  4. Components enabled/disabled per configuration