Upgrade Notes

Back up the project before upgrading. For a clean import, move your own assets and modified presets out of the old NWH folders, remove the old package files, then import the new version.

Follow the non-code steps for your version. If you have custom scripts or integrations, also check the Code section below.

Non-code

14.2 Beta 2 to 14.3.0

  • If you use FFB, update Unity-DirectInput using the setup guide and reimport Direct Input FFB Sample. Retune retired kerb, scrub, ABS, engine-resonance and shift-jolt effects using the current FFB controls.
  • Re-check CVT/External transmission types, wheel mass and load rating on vehicles saved in 14.0–14.2. Those versions could change the saved values.
  • Reimport samples with renamed folders; don't merge old and new copies. Back up sample customizations first.
  • For PUN2, keep PhotonMultiplayerVehicle last in Observed Components. See the Code section if you customized its send rates.

13.x to 14.x

  • Unity 6000.0.80f1 or newer required. Clean import recommended; install Vehicle Physics, Wheel Controller and Common together through Package Manager. URP is a dependency; for Built-in RP, use Tools > NWH > Convert Folder URP to Built-in.
  • Replace Unity WheelCollider setups with WheelController; the old backend is removed.
  • Transfer per-wheel friction settings to the StandardFriction component. It is added automatically with defaults, without your v13 tuning. Retune load sensitivity and friction ellipticity; the old values aren't equivalent.
  • Re-enter transmission gear ratios; gearing profiles are removed. Retune the differential's LSD ramp angles, preload torque and slip torque coefficient.
  • Re-enter vehicle dimensions on VehicleController. Retune spring progressiveness, anti-roll stiffness/damping and roll center height; the old suspension curves, anti-roll force and force application offset don't migrate directly.
  • Remove missing CamberController components. Set the camber curve on each WheelController and enable Use Camber Curve.
  • Replace SteeringWheelInputProvider using the FFB setup guide. Add both DirectInputManager and FFBInputProvider, then configure bindings and calibration.
  • Rewired providers and the Cinemachine camera setup are removed. Switch to the included input providers and camera modes, or update your own integration.
  • Assign the dashboard's vehicle reference, or select the active vehicle as its data source. Restore missing scene mesh/material references from the new assets.
  • Check engine sample base RPMs after the first Play, and restore custom sound positions on the engine and transmission. Retune sound, steering and damage settings that used removed fields.
  • Test each vehicle's handling. Friction presets and drivetrain inertia changed; retune engine/clutch settings and raise legacy ESC intensity into the current 1–30 range if needed. If ground detection is too costly, set StandardGroundDetection's cast type to Sphere.

11.x to 12.x

  • Clean import recommended
  • WheelController: rotatingVisual and nonRotatingVisual replaced with Rotating and NonRotating containers (use Upgrade from v11 button)
  • Differential: Single differential with adjustable settings replaces fixed types
    • Open: Stiffness = 0
    • LSD: Stiffness > 0, Slip torque ~200
    • Locked: Stiffness = 1, Slip torque > 1000

11.10f to 11.11f

  • Clean import required due to the resources that were moved.

10.x to 11.x

  • Unity 2020.3.40f minimum
  • Clean import required
  • Powertrain outputs need re-assignment
  • EngineStartComponent → EngineStartStopComponent (StateDefinition settings need re-assignment)
  • Clutch type changed to enum (re-assign if not Automatic)

9.x (1.9.x) to 10.x

  • MAJOR UPDATE - Clean import required (remove NWH folder completely)
  • Unity 2021.3.16f minimum
  • WheelController3D: Major rewrite, new API, Force Coefficient → Grip, Slip Coefficient → Stiffness
  • Vehicle:
    • NRigidbody removed (use Fixed Delta Time instead: 0.01-0.01667 for desktop)
    • Center of mass/inertia moved to optional VariableCenterOfMass script
    • Historical v10 migration: the old anti-roll bar was replaced at that time by Force Application Point Distance. That field is not part of the current v14 Wheel Controller; current projects use the ARB and roll-center controls.
    • Automatic Sequential transmission removed (use Automatic + Is Sequential)
    • Clutch PID replaced with clutchEngagementRPM and clutchEngagementRange
    • Wheel camber set on WheelController (not WheelGroup)
  • Scene: CharacterVehicleChanger integrated into VehicleChanger, tag-based vehicle finding removed

v1.8.x to v1.9.x (v9.x)

  • Clean import required.

v1.7.x to v1.8.x

  • Clean import required.

v1.7.5 to v1.7.6

  • Clean import required.

v1.7.3 to v1.7.4

  • Clean import required (asmdef changes)
  • Lateral friction calculation improved (may require friction coefficient adjustment)

v1.6.x to v1.7

  • Powertrain inertia changes (vehicles accelerate faster)
  • Multiplayer: NetworkRigidbody option added (don't use with NetworkTransform simultaneously)

v1.5.x to v1.6.x

  • Clean import required (asset restructuring)

  • .NET 4.x API Compatibility Level required

  • Multiple NWH assets require simultaneous update (Common folder restructure)

  • Torque converter removed (use clutch slip torque)

  • CVT uses single forward/reverse gear ratio (minimum ratio for each direction)

v1.5 to v1.5.1

  • PIDController.cs may duplicate on import (remove if occurs)

v1.4 to v1.5

  • Clean import required (folder restructure for multi-asset compatibility)
  • WheelController damper settings need ~50% reduction

v1.3 to v1.4

  • NRigidbody component now required (add manually to existing vehicles)

v1.2 to v1.3

  • No changes required

v1.1 to v1.2

  • Delete Scripts folder before upgrading (namespace changes)
  • InputProviders split: SceneInputProvider (scene input) + VehicleInputProvider (vehicle input)
  • Shared scripts moved to NWH/Common directory

v1.0 to v1.1

  • Delete Scripts > Vehicle > Input folder before upgrading
  • InputSystem package required (auto-installed)
  • InputManager binding changes:
    • Horizontal → Steering
    • Vertical split to Throttle and Brakes
    • Add: CameraRotation, CameraPanning, CameraRotationModifier, CameraPanningModifier, CameraZoom, FPSMovement, ToggleGUI

NWH Vehicle Physics 1 to NWH Vehicle Physics 2

  • Remove all previous NWH Vehicle Physics and Wheel Controller 3D versions
  • Manual vehicle upgrade required (major differences)
  • Use Vehicle Setup Wizard to expedite setup

Code

These steps apply only to custom scripts, assembly definitions or integrations.

14.2 Beta 2 to 14.3.0 (code)

  • Re-select NWH.WheelController assembly references created in 14.0–14.2. Replace Wheel Controller's MathUtility with WheelMathUtility.
  • Remove references to NWH.VehiclePhysics2.Tests and NWH.VehiclePhysics2.PlayModeTests. Add Burst yourself if your code needs it and no other package installs it.
  • Set Photon's global send rates in your networking setup; PhotonMultiplayerVehicle's old rate fields are ignored.
  • For custom controls, use runtime rebinding or your own Input Actions asset and provider. Shipped wrappers no longer regenerate on import.

13.x to 14.x (code)

  • Add float DeltaTime to VC_Update/VC_FixedUpdate overrides and base calls. Rename VC_SetVehicleController(VehicleController) to VC_Initialize(VehicleController), keeping the argument.
  • Point wheel references at WheelController and rename the old wheel fields to wheelController. Scene and prefab data migrates automatically. Update wheel access such as .Radius → .wheel.radius and .MotorTorque → .motorTorque. Access friction through StandardFriction.
  • Update engine power modifiers, shift callbacks and QueryInertia to take delta time; change LoadComponentFromHash(in int) to ref int.
  • Replace NVP_NUIEditor with NWH.VehiclePhysics2.VehiclePhysicsNUIEditor and NVP_NUIPropertyDrawer with NUIPropertyDrawer.
  • Update custom WheelCast implementations: distance excludes wheel radius, and the result must include localPoint in the wheel's local space.
  • For custom simulation rates, use WheelControllerGroup.targetEffectiveRateOverride; manual Step() calls no longer simulate wheels.
  • To keep Rewired, write an InputProvider integration.
  • For custom multiplayer code, include MultiplayerState.brakes and call GetMultiplayerState() from one place only; each call clears pending button events.
  • For custom trailer couplers, use the module-created collider and TrailerCouplerMarker; forwarding trigger calls to the hitch wrapper no longer works.

v1.5.x to v1.6.x (code)

  • Reference NVP2 from custom assembly definitions.
  • Configure the SteeringWheelInput assembly definition for the Logitech SDK used in this release.

v1.4 to v1.5 (code)

  • Input classes renamed: Input → VehicleInputHandler, InputStates → VehicleInputStates.