Class ClutchComponent

Friction clutch between the engine and the transmission. Slip torque sets the maximum transferable torque at a given engagement level; higher values engage faster, lower values are more progressive. Automatic, user-input and manual control modes.

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

Fields

brakeDisengageSpeed

Vehicle speed (m/s) below which heavy braking disengages the clutch. 0 falls back to lockupSpeed.

Declaration
[ShowInSettings("Brake Disengage Speed", 0, 10, 1)]
[Tooltip("Vehicle speed (m/s) below which heavy braking disengages the clutch. Set to 0 to follow Lockup Speed.")]
public float brakeDisengageSpeed
Field Value
Type Description
float

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

Torque floor applied ahead of the clutch capacity clamp to emulate torque converter creep on automatic transmissions. Still bounded by clutch engagement times slip torque, so a fully open clutch transmits none of it - creep only helps once the clutch has partial engagement. Applies while the engine is running and fades to zero at creepSpeedLimit. Should be higher than rolling resistance of the wheels to get the vehicle rolling.

Declaration
[Tooltip("Torque floor applied ahead of the clutch capacity clamp to emulate torque converter creep on automatic transmissions. Bounded by clutch engagement times slip torque, so a fully open clutch transmits none of it, and fades to zero at creepSpeedLimit. 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("Inert as shipped - clutch damage is never raised. Maximum slip torque reduction at full damage (0-1).")]
public float damageSlipTorqueReduction
Field Value
Type Description
float
Remarks

Inert as shipped. ClutchComponent.Damage is only ever reset to 0 - DamageHandler raises damage on the engine, the transmission and the wheels only - so this multiplies a permanent zero.

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

lockupProtectionBrakeThreshold

Brake input above which high-speed wheel-lock protection can disengage the clutch. Independent of the low-speed brake-disengagement threshold.

Declaration
[Range(0, 1)]
[Tooltip("Brake input threshold for high-speed wheel-lock protection.")]
public float lockupProtectionBrakeThreshold
Field Value
Type Description
float

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 squared, 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. The engine discards this return value and reads QueryReturnTorque() after the wheels have stepped, so QueryReturnTorque() is the live reaction path; a new node must override that one to be felt upstream.

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

Zeroes angular velocity and torque so the next enable starts clean.

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