Upgrade Notes
These notes apply to NWH Wheel Controller 3D. The installed package version is shown in the Package Manager.
Before upgrading, commit or back up the project and record any values that were customized in package assets. After the update, check the Changelog for intermediate versions and test vehicle prefabs in a copy of the project.
14.4.0 to 14.4.1
- A stopped wheel no longer holds a slope without brake torque. Its forward/back hold is limited to
brakeTorqueplusRolling Resistance Torque, so a vehicle that was parked on a slope with no brake applied now rolls. Apply brake torque while it is parked. The sideways hold is unchanged. With Vehicle Physics 2 this is covered by Brakes > Brake While Idle and Brake While Disabled, both on by default; a vehicle with Brake While Idle off rolls when left in neutral on a slope. - A custom
GroundDetectionBaseshould report the real contact point. The suspension now readslocalPoint.xas well as Y and Z and treats the tyre as round across its width. A wheel leaned relative to the ground rides lower by(width / 2) * (1 - cos(lean)), which motorcycles will see at lean.
14.3.x to 14.4.0
Friction Ellipticitynow ranges from 1 to 2, and saved values below 1 behave as 1. Retest vehicles whose friction component used a lower value.- The
Load Ratingwarning now compares the rating with the static load of one wheel and fires below 1.5x or above 4x of it when the wheel starts in Play mode. If it appears on an existing vehicle, set the rating to about twice the resting load or enableAuto Calculate Load Rating. - A custom
GroundDetectionBasehas to skip steep faces beside the tyre itself, asStandardGroundDetectionnow does. The suspension pushes along the returned normal with the full strut force, so a wall hit that used to give no load now pushes the wheel sideways.
14.2 Beta 2 to 14.3.0
WheelControllerManagerremains the only owner of wheel stepping. The legacyWheelController.Step(float, Matrix4x4)signature is present for source and binary compatibility, but is obsolete and performs no simulation. Remove manual calls; leaving them in place is safe while migrating.- The manager rounds requested rates up, not to the nearest integer, and always keeps an individual substep at or below 0.05 seconds (up to the eight-substep cap). Recheck any code or profiling budget that predicted substep counts from the old documentation formula.
- The shipped Ice and Arcade lateral friction data changed because the old curves did not reach a meaningful peak inside the lookup domain. Retest ABS/TCS thresholds, steering feel and handling if those presets are used as tuning baselines.
- Existing serialized friction and
StandardFrictiontuning remains serialized. New instances use the revised generic BCDE(12, 1.9, 1, 0.97), load sensitivity(0.85, 0.8), mechanical trail0.08 * radius, and a 512-sample LUT. Peak-slip fields are recomputed from the LUT at load. The former publicSetLateralAndRegenerate()editor entry point remains as an obsolete alias, but now uses the safe path and never overwrites lateral BCDE values.- The mechanical trail change is the one most likely to be noticed and the one an upgrade does
not deliver: a
StandardFrictionalready saved in a prefab or scene keeps its0.04, so its force feedback still goes light in a slide. Set Mechanical Trail to0.08by hand on existing vehicles if you want the new steering weight.
- The mechanical trail change is the one most likely to be noticed and the one an upgrade does
not deliver: a
FrictionBase.staticReEntryCooldownis afloatholding seconds, not anintsubstep count. Custom code that reads or writes it must change type. The field is not serialized, so no asset changes. The authoring knob, Re-Entry Cooldown (staticFrictionCooldownFrames), is unchanged in name, type and default, but is now interpreted as a count of 5 ms reference substeps rather than real substeps - so its wall-clock effect no longer moves with the solver rate.WheelController.SetRuntimeDefaultsIfNeeded()lost its second parameter, which was never read. CallFindOrSpawnVisualContainers()if you need the visual containers created.- The release project changed its physics defaults from 50 Hz to 60 Hz, solver position iterations
from 6 to 8, solver velocity iterations from 1 to 12, and default maximum angular speed from 7 to
50 rad/s. A UPM package update does not silently replace your project's
ProjectSettings; choose whether to apply each setting. Higher rates and iteration counts cost more CPU, while all four values can change handling and stability, so profile and retest vehicle tuning after applying them. - The shipped
CarInputActionswrapper no longer regenerates during package import. Use runtime rebinding or a project-owned action asset for project-specific controls. Maintainers editing a writable embedded package must explicitly enable Generate C# Class, regenerate and review the wrapper, then disable generation again before publishing.
13.x to 14.x
Requirements
- Unity 6000.0.80f1 or newer is required by the current package.
- Universal Render Pipeline and Unity's Input System are package dependencies.
Manager-Driven Wheel Stepping
WheelControllerManager now owns wheel simulation and substepping:
- Each enabled
WheelControllerregisters itself with the singleton manager. - The manager groups wheels by their parent
Rigidbody. - During the manager's
FixedUpdate(), it calculates 1 to 8 substeps fromtargetEffectiveRateandTime.fixedDeltaTime. - At the end of the physics tick, the manager applies the accumulated state and visual transforms.
Do not replace old manual stepping code with another direct wheel call. Keep each Wheel Controller
enabled under its target Rigidbody and let WheelControllerManager run it. The manager creates
itself when the first enabled wheel requests the singleton, so a standalone scene does not require
a manually added manager object.
If runtime code changes a wheel's radius, width, mass, transform, or the vehicle's colliders, call the current public reinitialization method:
using NWH.WheelController3D;
using UnityEngine;
public class WheelRuntimeConfiguration : MonoBehaviour
{
[SerializeField] private WheelController wheel;
public void ApplyChanges()
{
wheel.Initialize();
WheelControllerManager.Instance.targetEffectiveRate = 200f;
}
}
The second line in ApplyChanges() sets the manager's global target rate to 200 Hz.
Friction Component
Friction calculation is provided by a separate StandardFriction component. WheelController
adds it when no FrictionBase component is present. Code that changes friction-specific settings
should retrieve StandardFriction from the same GameObject; the active tire curve remains
available through WheelController.activeFrictionPreset.
Anti-Roll Bar
The current Wheel Controller exposes arbStiffness and arbDamping. A value of 0 for
arbStiffness disables the anti-roll bar for that wheel.
11.x to 12.x Visual Containers
The old visual references were replaced by child containers:
Rotatingcontains the wheel mesh and other parts that spin.NonRotatingcontains parts such as brake calipers that follow steering but do not spin.
To migrate an existing wheel, select its WheelController, open Misc > Legacy / Migration, and
click Upgrade from v11. The current inspector also provides Misc > Setup Actions > Generate
Visual Containers for manual setup.

Input and Assemblies
The standalone Base Sample CarController uses the shipped CarInputActions Input System wrapper.
See Input for the current bindings and lifecycle.
The package assembly is NWH.WheelController. Scripts in a custom assembly definition must
reference that assembly; NWH.WheelController3D is the namespace, not the assembly name. Keep the
package assembly definitions in place. See Import Guide.