Class ClutchComponent

Clutch component that manages power transmission between engine and transmission through controlled friction coupling with realistic slip characteristics.

Inheritance
object
VehicleComponent
PowertrainComponent
ClutchComponent
Inherited Members
Namespace: NWH.VehiclePhysics2.Powertrain
Assembly: NWH.VehiclePhysics2.dll
Syntax
[Serializable]
public class ClutchComponent : PowertrainComponent
Remarks

The ClutchComponent simulates a friction clutch system that allows smooth engagement and disengagement of power between the engine and transmission. It supports multiple control modes from fully automatic operation to complete manual control, providing realistic clutch behavior for different vehicle types.

Key features include: - Progressive clutch engagement with slip torque modeling - Multiple control modes: Automatic, User Input, and Manual - Torque converter simulation for automatic transmissions - Creep function for low-speed maneuvering - Damage-based slip torque reduction and stall prevention - Integration with transmission shift logic

The clutch uses slip torque to determine maximum transferable torque at any engagement level. Higher slip torque values create more sensitive clutches that engage quickly, while lower values provide smoother, more progressive engagement. Automatic mode handles clutch operation based on engine RPM and vehicle speed, while manual modes allow direct player or script control.

Fields

brakeDisengageThreshold

Brake input threshold above which clutch starts to disengage at low speeds. Set to 1 to disable brake-based disengagement.

Declaration
[ShowInSettings("Brake Disengage Threshold", 0, 1, 0.1)]
[Tooltip("Brake input level above which the clutch starts disengaging at low speeds. Set to 1 to disable.")]
public float brakeDisengageThreshold
Field Value
Type Description
float

clutchInput

Clutch engagement in range [0,1] where 1 is fully engaged clutch. Affected by Slip Torque field as the clutch can transfer [clutchEngagement * slipTorque] Nm meaning that higher value of slipTorque will result in a more sensitive clutch.

Declaration
[Range(0, 1)]
[Tooltip("Clutch engagement in range [0,1] where 1 is fully engaged clutch.\r\nAffected by Slip Torque field as the clutch can transfer [clutchEngagement * slipTorque] Nm\r\nmeaning that higher value of slipTorque will result in more sensitive clutch.")]
[ShowInTelemetry(0, 1, "0.00", null, 1)]
public float clutchInput
Field Value
Type Description
float

controlType

Method used to control clutch engagement: Automatic, UserInput or Manual.

Declaration
[Tooltip("Method used to control clutch engagement: Automatic, UserInput or Manual.")]
public ClutchComponent.ClutchControlType controlType
Field Value
Type Description
ClutchComponent.ClutchControlType

creepSpeedLimit

Vehicle speed (m/s) below which creep torque is applied.

Declaration
[Tooltip("Vehicle speed (m/s) below which creep torque is applied.")]
public float creepSpeedLimit
Field Value
Type Description
float

creepTorque

The amount of torque that will be passed through clutch even when completely disengaged to emulate torque converter creep on automatic transmissions. Should be higher than rolling resistance of the wheels to get the vehicle rolling.

Declaration
[Tooltip("Amount of torque that will be passed through clutch even when completely disengaged to emulate torque converter creep on automatic transmissions.Should be higher than rolling resistance of the wheels to get the vehicle rolling.")]
[ShowInSettings("Creep Torque", 0, 100, 10)]
public float creepTorque
Field Value
Type Description
float

damageSlipTorqueReduction

Maximum slip torque reduction at full damage (0-1). 0.6 = 60% slip torque loss at damage=1.

Declaration
[Range(0, 1)]
[Tooltip("Maximum slip torque reduction at full damage (0-1). 0.6 = 60% slip torque loss when damage=1.")]
public float damageSlipTorqueReduction
Field Value
Type Description
float

engagementCurve

Curve representing pedal travel vs. clutch engagement. Should start at 0,0 and end at 1,1.

Declaration
[Tooltip("Curve representing pedal travel vs. clutch engagement. Should start at 0,0 and end at 1,1.")]
[FormerlySerializedAs("clutchEngagementCurve")]
public AnimationCurve engagementCurve
Field Value
Type Description
AnimationCurve

engagementRPM

RPM at which automatic clutch will try to engage.

Declaration
[FormerlySerializedAs("baseEngagementRPM")]
[ShowInTelemetry(0, 3000, "0", "RPM", 1)]
[ShowInSettings("Engagement RPM", 900, 2000, 100)]
[Tooltip("RPM at which automatic clutch will try to engage.")]
public float engagementRPM
Field Value
Type Description
float

engagementRange

The RPM range in which the clutch will go from disengaged to engaged and vice versa. E.g., if set to 400 and engagementRPM is 1000, 1000 will mean clutch is fully disengaged and 1400 fully engaged. Setting it too low might cause the clutch to hunt/oscillate.

Declaration
[ShowInSettings("Engagement Range", 200, 1000, 100)]
[Tooltip("The RPM range in which the clutch will go from disengaged to engaged and vice versa. \r\nE.g. if set to 400 and engagementRPM is 1000, 1000 will mean clutch is fully disengaged and\r\n1400 fully engaged. Setting it too low might cause clutch to hunt/oscillate.")]
public float engagementRange
Field Value
Type Description
float

highSpeedLockupProtection

Enable clutch disengagement when wheels lock up at high speed to prevent engine stall.

Declaration
[Tooltip("Enable clutch disengagement when wheels lock up at high speed to prevent engine stall.")]
public bool highSpeedLockupProtection
Field Value
Type Description
bool

lockupProtectionActive

True while high-speed lockup protection is actively disengaging the clutch.

Declaration
[NonSerialized]
[ShowInTelemetry(NaN, NaN, null, null, 1)]
public bool lockupProtectionActive
Field Value
Type Description
bool

lockupProtectionMinSpeed

Minimum speed (m/s) for high-speed lockup protection to activate.

Declaration
[ShowInSettings("Lockup Protection Min Speed", 2, 20, 1)]
[Tooltip("Minimum speed (m/s) for high-speed lockup protection to activate.")]
public float lockupProtectionMinSpeed
Field Value
Type Description
float

lockupRPMFactor

RPM factor above idle RPM required for high-speed lockup.

Declaration
[ShowInSettings("Lockup RPM Factor", 1, 1.5, 0.05)]
[Tooltip("Engine RPM must be above (idleRPM * this factor) for high-speed clutch lockup.")]
public float lockupRPMFactor
Field Value
Type Description
float

lockupSlipThreshold

Longitudinal slip threshold that triggers lockup protection. Higher = later intervention.

Declaration
[Range(0.1, 0.9)]
[ShowInSettings("Lockup Slip Threshold", 0.1, 0.9, 0.05)]
[Tooltip("Longitudinal slip threshold that triggers lockup protection. Higher = later intervention.")]
public float lockupSlipThreshold
Field Value
Type Description
float

lockupSpeed

Speed above which engagement blends toward full lockup, provided engine RPM is also above idleRPM * lockupRPMFactor.

Declaration
[ShowInSettings("Lockup Speed", 1, 10, 1)]
[Tooltip("Vehicle speed (m/s) above which the clutch blends toward full engagement, once engine RPM is above idleRPM * lockupRPMFactor.")]
public float lockupSpeed
Field Value
Type Description
float

rpmMatchTolerance

Fraction of RPM difference allowed for re-engagement. Lower = smoother but slower.

Declaration
[Range(0.05, 0.4)]
[ShowInSettings("RPM Match Tolerance", 0.05, 0.4, 0.05)]
[Tooltip("Fraction of RPM difference allowed for re-engagement. Lower = smoother but slower.")]
public float rpmMatchTolerance
Field Value
Type Description
float

slipTorque

Torque at which the clutch will slip / maximum torque that the clutch can transfer. This value also affects clutch engagement as a higher slip value will result in a clutch that grabs higher up / sooner. Too high slip torque value combined with low inertia of powertrain components might cause instability in the powertrain solver.

Declaration
[SerializeField]
[Tooltip("Torque at which the clutch will slip / maximum torque that the clutch can transfer.\r\nThis value also affects clutch engagement as higher slip value will result in clutch\r\nthat grabs higher up / sooner. Too high slip torque value combined with low inertia of\r\npowertrain components might cause instability in powertrain solver.")]
[ShowInSettings("Slip Torque", 10, 5000, 100)]
public float slipTorque
Field Value
Type Description
float

throttleEngagementOffsetRPM

Additional RPM added to engagementRPM, scaled by throttle squared, so the clutch engages higher up under throttle.

Declaration
[Tooltip("Additional RPM added to the engagement RPM, scaled by throttle, so the clutch engages higher up under throttle.")]
public float throttleEngagementOffsetRPM
Field Value
Type Description
float

Properties

Engagement

Clutch engagement based on clutchInput and the clutchEngagementCurve

Declaration
[ShowInTelemetry(0, 1, "0.00", null, 1)]
public float Engagement { 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
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 clutch component as the midpoint between engine and transmission.

Declaration
public override Vector3 GetWorldPosition(VehicleController vc)
Parameters
Type Name Description
VehicleController vc

The vehicle controller.
Returns
Type Description
Vector3

Clutch position in world space.
Overrides

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
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
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

QueryTorqueCapacity()

Maximum torque magnitude the clutch can transmit at the current engagement, after damage. The engine uses this to bound how fast it synchronizes to the drivetrain so it cannot sync faster than the friction surface can physically transmit.

Declaration
public override float QueryTorqueCapacity()
Returns
Type Description
float
Overrides

UpdateClutchInput()

Finalizes clutchInput once per FixedUpdate, before engine integration, so every substep pass reads one engagement value.

Declaration
public void UpdateClutchInput()

VC_Disable(bool)

Disables the powertrain component and resets its operational values.

Declaration
public override bool VC_Disable(bool calledByParent)
Parameters
Type Name Description
bool calledByParent

True if this method was called by a parent component, false if called directly.
Returns
Type Description
bool

True if the component was successfully disabled, false otherwise.
Overrides
Remarks

When disabled, all angular velocity and torque values are reset to zero to ensure a clean state for the next time the component is enabled.

VC_SetDefaults()

Sets the component's properties to their default values.

Declaration
public override void VC_SetDefaults()
Overrides
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
Remarks

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

See Also