Class DifferentialComponent

Differential component that distributes torque between two outputs (typically left and right wheels) while allowing speed differences during cornering and varying traction conditions.

Inheritance

object

VehicleComponent

PowertrainComponent

DifferentialComponent

Inherited Members

PowertrainComponent.MIN_INERTIA

PowertrainComponent.inertia

PowertrainComponent.position

PowertrainComponent.inputAngularVelocity

PowertrainComponent.inputInertia

PowertrainComponent.inputNameHash

PowertrainComponent.inputName

PowertrainComponent.inputTorque

PowertrainComponent.name

PowertrainComponent.outputAngularVelocity

PowertrainComponent.outputInertia

PowertrainComponent.outputNameHash

PowertrainComponent.outputName

PowertrainComponent.outputTorque

PowertrainComponent._damage

PowertrainComponent._input

PowertrainComponent._output

PowertrainComponent.Input

PowertrainComponent.Output

PowertrainComponent.Damage

PowertrainComponent.InputRPM

PowertrainComponent.OutputRPM

PowertrainComponent.VC_Disable(bool)

PowertrainComponent.QueryTorqueCapacity()

PowertrainComponent.PC_LogWarning(VehicleController, string)

PowertrainComponent.TorqueToPowerInKW(in float, in float)

PowertrainComponent.PowerInKWToTorque(in float, in float)

PowertrainComponent.CalculateOutputPowerInKW()

PowertrainComponent.GetPowerInKW(in float, in float)

PowertrainComponent.LoadComponentFromHash(in VehicleController, ref PowertrainComponent, ref int)

PowertrainComponent.LoadComponent(in VehicleController, ref PowertrainComponent, ref string, ref int)

VehicleComponent.state

VehicleComponent.vehicleController

VehicleComponent.IsActive

VehicleComponent.VC_Initialize(VehicleController)

VehicleComponent.VC_FixedUpdate(float)

VehicleComponent.VC_LoadStateFromStateSettings()

VehicleComponent.VC_Update(float)

VehicleComponent.VC_Enable(bool)

VehicleComponent.VC_DrawGizmos()

VehicleComponent.UpdateLOD()

VehicleComponent.ToggleState()

Namespace: NWH.VehiclePhysics2.Powertrain

Assembly: NWH.VehiclePhysics2.dll

Syntax

[Serializable]
public class DifferentialComponent : PowertrainComponent

Remarks

The DifferentialComponent simulates various differential types including open, locked, limited-slip differentials (LSD), and Torsen gear-type differentials. It manages torque distribution between outputs based on load conditions, speed differences, and configured settings to provide realistic handling characteristics.

Key features include: - Multiple differential types: Open, LSD, Locked, and Torsen - Configurable torque bias between left and right outputs - Realistic ramp angle simulation for clutch-type LSDs - Separate preload and slip torque for accurate LSD behavior - Torque-biasing ratio for Torsen differentials - Support for differential steering in specialized vehicles - Integration with traction control and stability systems - Smooth power/coast transitions and hysteresis for stability at 50Hz

The LSD type uses ramp angles to define locking behavior: shallower/lower angles provide more aggressive locking. Power ramp angle controls locking under acceleration, coast ramp angle under braking. Setting coast to 80-90° creates a 1-way LSD (drift style), equal angles create a 2-way (race style), higher coast than power creates 1.5-way.

Fields

_outputB

Declaration

[NonSerialized]
protected PowertrainComponent _outputB

Field Value

Type	Description
PowertrainComponent

actualTorqueSplitAB

Current torque split between outputs. -1 = all to A, 0 = balanced, +1 = all to B. Useful for tuning and debugging.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
[NonSerialized]
public float actualTorqueSplitAB

Field Value

Type	Description
float

biasAB

Torque bias between left (A) and right (B) output in [0,1] ranges.

Declaration

[SerializeField]
[Range(0, 1)]
[ShowInTelemetry(NaN, NaN, null, null, 1)]
[ShowInSettings("Bias A/B", 0, 1, 0.1)]
[Tooltip("Torque bias between left (A) and right (B) output in [0,1] ranges.")]
public float biasAB

Field Value

Type	Description
float

coastRampAngle

Ramp angle for coast/braking in degrees. Controls locking under engine braking. Set to 0 or 90 for 1-way LSD (no coast lock), equal to powerRampAngle for 2-way, higher than power for 1.5-way.

Declaration

[Range(1, 89)]
[Tooltip("Coast ramp angle (degrees). 90° = 1-way LSD (no coast lock), same as power = 2-way (race), higher than power = 1.5-way (street).")]
[ShowInSettings("Coast Ramp Angle", 1, 89, 5)]
public float coastRampAngle

Field Value

Type	Description
float

correctiveTorque

Corrective torque being applied by the differential mechanism to resist speed difference. Shows how hard the diff is working. Higher absolute value = more locking force being applied.

Declaration

[ShowInTelemetry(-2000, 2000, "0.0", "Nm", 1)]
[NonSerialized]
public float correctiveTorque

Field Value

Type	Description
float

damageLsdEffectivenessReduction

LSD effectiveness reduction at full damage (0-1). 0.7 = 70% LSD effectiveness loss at damage=1.

Declaration

[Range(0, 1)]
[Tooltip("LSD effectiveness reduction at full damage (0-1). 0.7 = 70% loss when damage=1.")]
public float damageLsdEffectivenessReduction

Field Value

Type	Description
float

damagePreloadReduction

Preload reduction at full damage (0-1). 0.5 = 50% preload loss at damage=1.

Declaration

[Range(0, 1)]
[Tooltip("Preload reduction at full damage (0-1). 0.5 = 50% preload loss when damage=1.")]
public float damagePreloadReduction

Field Value

Type	Description
float

differentialSteering

If true, the torque will be sent to left/right based on the steering input.

Declaration

[Tooltip("If true, the torque will be sent to left/right based on the steering input.")]
public bool differentialSteering

Field Value

Type	Description
bool

differentialType

Type of differential mechanism.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
[Tooltip("Type of differential mechanism. LSD uses ramp angles, Torsen uses TBR, Locked ignores other settings.")]
public DifferentialType differentialType

Field Value

Type	Description
DifferentialType

gearRatio

Gear ratio for this differential. Scales angular velocity reported upstream and torque received. Use to compensate for different wheel sizes on connected axles. Default 1.0 (no effect). Example: If rear wheels are 1.25x larger than front, set rear diff ratio to 1.25.

Declaration

[Range(0.1, 10)]
[Tooltip("Gear ratio for wheel size compensation. 1.0 = no change. Set to wheelDiameter ratio to compensate for different wheel sizes between axles.")]
[ShowInSettings("Gear Ratio", 0.1, 10, 0.1)]
public float gearRatio

Field Value

Type	Description
float

lockedDamping

Damping coefficient for locked differential. Helps prevent oscillation by resisting rapid speed changes. Set to 0 for pure proportional control. Typical: 100-500 for additional stability.

Declaration

[Range(0, 2000)]
[Tooltip("Locked diff damping (N·m per rad/s²). Prevents oscillation. 0 = off, 200 = mild damping, 500+ = heavy damping. Use if seeing jitter.")]
public float lockedDamping

Field Value

Type	Description
float

lockedMaxTorqueMultiplier

Multiplier for max corrective torque relative to input torque. Prevents physics explosion on stuck wheels while allowing high torque.

Declaration

[Range(1, 10)]
[Tooltip("Max corrective torque multiplier. Higher = more rigid lock but may oscillate. Default 3 = 3x input torque.")]
public float lockedMaxTorqueMultiplier

Field Value

Type	Description
float

lockedStiffness

Locked-diff firmness [0,1] scaling the equalizing impulse (1 = rigid lock). Legacy values >1 clamp.

Declaration

[Range(0, 1)]
[Tooltip("Locked diff firmness (0-1). 1 = rigid lock, lower = softer.")]
public float lockedStiffness

Field Value

Type	Description
float

lockingPercentage

Current locking percentage (0-1). Shows how much the differential is locked right now. 0 = fully open, 1 = fully locked. Useful for tuning and debugging.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
[NonSerialized]
public float lockingPercentage

Field Value

Type	Description
float

lsdResponseRate

How quickly the LSD locks/unlocks. Higher = faster response but may oscillate at low physics rates. Range: 0.1 (slow, smooth) to 1.0 (instant). Typical: 0.3 for 50Hz, 0.5 for 120Hz+.

Declaration

[Range(0.05, 1)]
[Tooltip("LSD response rate. Higher = faster lock/unlock. 0.3 = smooth for 50Hz, 0.5-0.8 = for high physics rates.")]
public float lsdResponseRate

Field Value

Type	Description
float

outputBName

Name of the second output component, persisted for stable link reconstruction across runtime sessions. Preferred over outputBNameHash which is kept as a legacy fallback.

Declaration

[SerializeField]
public string outputBName

Field Value

Type	Description
string

outputBNameHash

Declaration

public int outputBNameHash

Field Value

Type	Description
int

powerCoastBlendZone

Torque range in Nm over which power/coast transition is smoothed. Prevents abrupt handling changes at throttle lift. Typical: 50-200 Nm.

Declaration

[Tooltip("Torque range (Nm) for smooth power/coast transition. Prevents sudden handling changes at throttle lift. Typical: 100 Nm.")]
public float powerCoastBlendZone

Field Value

Type	Description
float

powerRampAngle

Ramp angle for power/acceleration in degrees. Controls locking aggression under power. Lower/shallower angle = more aggressive locking. Typical: 45° baseline, 30° aggressive (drift), 60° mild (street).

Declaration

[Range(1, 89)]
[Tooltip("Power ramp angle (degrees). Lower angle = more aggressive locking under acceleration. 45° = baseline, 30° = aggressive drift, 60° = mild street.")]
[ShowInSettings("Power Ramp Angle", 1, 89, 5)]
public float powerRampAngle

Field Value

Type	Description
float

preloadTorque

Preload torque in Nm. Base locking force always present in LSD, even when unloaded. Prevents one-wheel spin, affects turn-in behavior. Typical: 50-150 Nm.

Declaration

[Tooltip("Preload torque (Nm). Base locking force in LSD. Typical: 50-150 Nm for street, 100-200 Nm for race.")]
[ShowInSettings("Preload Torque", 0, 300, 50)]
public float preloadTorque

Field Value

Type	Description
float

slipTorqueCoefficient

Slip torque coefficient for load-dependent locking. Multiplies input torque to determine locking strength. Higher = more aggressive load-sensitive locking. Typical: 0.3-0.8 for street, 0.5-1.2 for race.

Declaration

[Range(0, 2)]
[Tooltip("Slip torque coefficient. Determines load-dependent locking strength (torque × coefficient). Typical: 0.5 for street, 0.8 for race.")]
[ShowInSettings("LSD Slip Coefficient", 0, 2, 0.1)]
public float slipTorqueCoefficient

Field Value

Type	Description
float

speedDifference

Speed difference between output A and output B in rad/s (Wa - Wb). Shows why the differential is working to lock. Positive = A spinning faster than B.

Declaration

[ShowInTelemetry(-500, 500, "0.0", "rad/s", 1)]
[NonSerialized]
public float speedDifference

Field Value

Type	Description
float

steeringRange

Maximum differential steering range (0-1). At 0.8, full steering input gives 80% torque difference. Prevents track reversal at full steering lock.

Declaration

[Range(0.1, 1)]
[Tooltip("Maximum differential steering range (0-1). At 0.8, full steering gives 80% torque difference. Prevents track reversal.")]
public float steeringRange

Field Value

Type	Description
float

torqueA

Torque sent to output A (left). Shows actual torque after LSD correction.

Declaration

[ShowInTelemetry(-2000, 2000, "0.0", "Nm", 1)]
[NonSerialized]
public float torqueA

Field Value

Type	Description
float

torqueB

Torque sent to output B (right). Shows actual torque after LSD correction.

Declaration

[ShowInTelemetry(-2000, 2000, "0.0", "Nm", 1)]
[NonSerialized]
public float torqueB

Field Value

Type	Description
float

torqueBiasRatio

Torque bias ratio for Torsen differential. How much more torque can be sent to one wheel vs the other. Typical: 2.5-4.0. Higher = more bias to wheel with traction, but less ability to help stuck wheel.

Declaration

[Range(1, 10)]
[Tooltip("Torque Bias Ratio for Torsen type. How much more torque the high-traction wheel can receive. Typical: 2.5-4.0 for AWD center diff.")]
[ShowInSettings("Torque Bias Ratio", 1, 10, 0.5)]
public float torqueBiasRatio

Field Value

Type	Description
float

Properties

OutputA_Name

Name of output A component for debugging context.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public string OutputA_Name { get; }

Property Value

Type	Description
string

OutputA_RPM

Output A angular velocity in RPM for easy visualization.

Declaration

[ShowInTelemetry(0, 8000, "0", "RPM", 1)]
public float OutputA_RPM { get; }

Property Value

Type	Description
float

OutputB

Second output of differential.

Declaration

public PowertrainComponent OutputB { get; set; }

Property Value

Type	Description
PowertrainComponent

OutputB_Name

Name of output B component for debugging context.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public string OutputB_Name { get; }

Property Value

Type	Description
string

OutputB_RPM

Output B angular velocity in RPM for easy visualization.

Declaration

[ShowInTelemetry(0, 8000, "0", "RPM", 1)]
public float OutputB_RPM { get; }

Property Value

Type	Description
float

Methods

ForwardStep(float, float, float)

Performs the forward pass of torque transmission through the powertrain chain.

Declaration

public override float ForwardStep(float torque, float inertiaSum, float DeltaTime)

Parameters

Type	Name	Description
float	torque	The input torque in N⋅m.
float	inertiaSum	The accumulated inertia of all upstream components in kg⋅m².
float	DeltaTime	The simulation delta time in seconds.

Returns

Type	Description
float	The final torque after processing through all connected components.

Overrides

PowertrainComponent.ForwardStep(float, float, float)

Remarks

Part of solver pass 2: propagates torque from engine toward wheels. Components apply gear ratios, losses, etc. Returns input torque if no output connected.

GetWorldPosition(VehicleController)

Gets the world position of the differential component. Calculates position as midpoint between its two outputs.

Declaration

public override Vector3 GetWorldPosition(VehicleController vc)

Parameters

Type	Name	Description
VehicleController	vc

Returns

Type	Description
Vector3

Overrides

PowertrainComponent.GetWorldPosition(VehicleController)

QueryAngularVelocity(float, float)

Queries and propagates angular velocity through the powertrain chain.

Declaration

public override float QueryAngularVelocity(float angularVelocity, float dt)

Parameters

Type	Name	Description
float	angularVelocity	The input angular velocity in rad/s.
float	dt	The simulation delta time in seconds.

Returns

Type	Description
float	The final angular velocity after propagation through all connected components.

Overrides

PowertrainComponent.QueryAngularVelocity(float, float)

Remarks

Part of solver pass 1: propagates angular velocity from wheels toward engine. Returns input velocity unchanged if no output is connected.

QueryInertia(float)

Queries and accumulates inertia values through the powertrain chain.

Declaration

public override float QueryInertia(float DeltaTime)

Parameters

Type	Name	Description
float	DeltaTime	The simulation delta time in seconds.

Returns

Type	Description
float	The total inertia of this component and all connected downstream components in kg⋅m².

Overrides

PowertrainComponent.QueryInertia(float)

Remarks

Adds this component's inertia to downstream components' accumulated inertia. Higher total inertia = slower acceleration, lower = more responsive.

QueryReturnTorque()

Queries the return torque (counterTorque) from downstream components after wheels have been stepped. Called after ForwardStep and wheel SubStep to get fresh counterTorque values.

Declaration

public override float QueryReturnTorque()

Returns

Type	Description
float	The accumulated return torque from all downstream components.

Overrides

PowertrainComponent.QueryReturnTorque()

VC_Initialize()

Initializes the powertrain component and establishes connections with other components.

Declaration

protected override void VC_Initialize()

Overrides

PowertrainComponent.VC_Initialize()

Remarks

Called during vehicle initialization. Validates inertia and loads component connections from stored name hashes.

VC_SetDefaults()

Sets the component's properties to their default values.

Declaration

public override void VC_SetDefaults()

Overrides

PowertrainComponent.VC_SetDefaults()

Remarks

Sets inertia to 0.02 kg⋅m², suitable for most powertrain components.

VC_Validate(VehicleController)

Validates the powertrain component configuration and logs warnings for potential issues.

Declaration

public override void VC_Validate(VehicleController vc)

Parameters

Type	Name	Description
VehicleController	vc	The vehicle controller that contains this component.

Overrides

PowertrainComponent.VC_Validate(VehicleController)

Remarks

Checks inertia minimum (0.0001) and output connections. Called during vehicle validation.