Class PowertrainComponent

Base class for all powertrain components in NWH Vehicle Physics 2.

Inheritance

object

VehicleComponent

PowertrainComponent

ClutchComponent

DifferentialComponent

EngineComponent

TransmissionComponent

WheelComponent

Inherited Members

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 abstract class PowertrainComponent : VehicleComponent

Remarks

The PowertrainComponent serves as the foundational class for all powertrain elements, including EngineComponent, ClutchComponent, TransmissionComponent, DifferentialComponent, and WheelComponent. It implements a physically accurate solver based on torque and angular velocity calculations.

Powertrain components are connected in a chain where each component can output to one or more other components, except for WheelComponent which always outputs to WheelController. The EngineComponent acts as the power source, while WheelComponent acts as the power sink. Components in between determine how power and torque are transmitted through the drivetrain.

Each component contributes its inertia to the overall system inertia, which determines how difficult it is to spin the powertrain up or down. Higher inertia values result in slower spin-up and spin-down characteristics, affecting vehicle responsiveness and stall resistance.

Important: Always ensure that inertia values are greater than 0. Modifying the name of a component will reset all outputs for other PowertrainComponents that depend on it.

Fields

MIN_INERTIA

Minimum allowed inertia value to prevent numerical instabilities in the powertrain solver.

Declaration

public const float MIN_INERTIA = 0.0001

Field Value

Type	Description
float

_damage

Damage level of the component ranging from 0 (no damage) to 1 (completely damaged).

Declaration

protected float _damage

Field Value

Type	Description
float

_input

Reference to the powertrain component that provides input to this component.

Declaration

[NonSerialized]
protected PowertrainComponent _input

Field Value

Type	Description
PowertrainComponent

_output

Reference to the powertrain component that receives output from this component.

Declaration

[NonSerialized]
protected PowertrainComponent _output

Field Value

Type	Description
PowertrainComponent

inertia

Angular inertia of the powertrain component in kg⋅m².

Declaration

[Range(0.0002, 2)]
[Tooltip("Angular inertia of the component. Higher inertia value will result in a powertrain that is slower to spin up, but\r\nalso slower to spin down. Too high values will result in (apparent) sluggish response while too low values will\r\nresult in vehicle being easy to stall.")]
public float inertia

Field Value

Type	Description
float

Remarks

Represents the rotational inertia of this component, which contributes to the overall system inertia. Higher inertia values result in a powertrain that is slower to spin up but also slower to spin down.

Effects of different values:

Low values (0.001-0.01): Very responsive powertrain, but easy to stall and may cause instability
Medium values (0.02-0.2): Balanced response suitable for most vehicles
High values (0.5+): Sluggish response, difficult to stall, suitable for heavy machinery

Typical values: Sports car components (0.01-0.05), average car components (0.02-0.1), truck components (0.1-0.5). Must always be greater than 0.0001.

inputAngularVelocity

Current input angular velocity in rad/s.

Declaration

[ShowInTelemetry(0, 1000, null, null, 1)]
public float inputAngularVelocity

Field Value

Type	Description
float

Remarks

This value is automatically set during the powertrain calculation process and represents the angular velocity being transmitted to this component from its input component.

inputInertia

Combined inertia of all components upstream from this component in kg⋅m².

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public float inputInertia

Field Value

Type	Description
float

Remarks

This value accumulates the inertia of all powertrain components that are connected before this component in the power transmission chain.

inputName

Name of the input component, persisted for stable link reconstruction across runtime sessions.

Declaration

[SerializeField]
public string inputName

Field Value

Type	Description
string

Remarks

Name-based lookup is stable across Unity versions; the legacy inputNameHash is not. Automatically managed by the system.

inputNameHash

Hash code of the input component's name for fast lookup. Legacy fallback for link persistence.

Declaration

public int inputNameHash

Field Value

Type	Description
int

Remarks

Used internally for efficient powertrain component linking. Automatically managed by the system. Primary persistence now uses inputName; this hash is kept to migrate older saved data.

inputTorque

Current input torque in N⋅m.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public float inputTorque

Field Value

Type	Description
float

Remarks

This value is automatically set during the powertrain calculation process and represents the torque being transmitted to this component from its input component.

name

Unique identifier for this powertrain component.

Declaration

[SerializeField]
[Tooltip("Name of the component. Only unique names should be used on the same vehicle.")]
public string name

Field Value

Type	Description
string

Remarks

Each component must have a unique name within the same vehicle. This name is used to establish connections between powertrain components and for component identification.

Warning: Changing the name of a component will reset all output connections for other PowertrainComponents that reference this component as their output.

outputAngularVelocity

Current output angular velocity in rad/s.

Declaration

[ShowInTelemetry(0, 1000, null, null, 1)]
public float outputAngularVelocity

Field Value

Type	Description
float

Remarks

This value represents the angular velocity that this component transmits to its output component(s). It may differ from inputAngularVelocity due to gear ratios or other transmission characteristics.

outputInertia

Combined inertia of all components downstream from this component in kg⋅m².

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public float outputInertia

Field Value

Type	Description
float

Remarks

This value includes the inertia of this component plus all components that are connected after this component in the power transmission chain.

outputName

Name of the output component, persisted for stable link reconstruction across runtime sessions.

Declaration

[SerializeField]
public string outputName

Field Value

Type	Description
string

Remarks

Name-based lookup is stable across Unity versions; the legacy outputNameHash is not. Automatically managed by the system.

outputNameHash

Hash code of the output component's name for fast lookup. Legacy fallback for link persistence.

Declaration

public int outputNameHash

Field Value

Type	Description
int

Remarks

Used internally for efficient powertrain component linking. Automatically managed by the system. Primary persistence now uses outputName; this hash is kept to migrate older saved data.

outputTorque

Current output torque in N⋅m.

Declaration

[ShowInTelemetry(NaN, NaN, null, null, 1)]
public float outputTorque

Field Value

Type	Description
float

Remarks

This value represents the torque that this component transmits to its output component(s). It may differ from inputTorque due to losses, gear ratios, or other transmission characteristics.

position

Position of the powertrain component in local space relative to the vehicle transform.

Declaration

[Tooltip("Position of the component relative to the vehicle. Used for gizmos and sound positioning.")]
public Vector3 position

Field Value

Type	Description
Vector3

Remarks

Used for visual representation, sound positioning, and powertrain visualization. Shown as a gizmo in Scene view when debug gizmos are enabled. Some components (like differentials) may calculate position dynamically based on outputs.

Properties

Damage

Gets or sets the damage level of the powertrain component.

Declaration

public float Damage { get; set; }

Property Value

Type	Description
float

Remarks

Damage level ranges from 0 (no damage) to 1 (completely damaged). Damage affects vehicle performance and handling characteristics.

Damage effects:

0.0: Component operates at full efficiency
0.0-0.3: Minor performance degradation
0.3-0.7: Significant performance loss and handling issues
0.7-1.0: Severe damage, component may fail completely

Input

Gets or sets the powertrain component that provides input to this component.

Declaration

public PowertrainComponent Input { get; set; }

Property Value

Type	Description
PowertrainComponent

Remarks

This property is automatically managed by the powertrain system when components are connected. Setting this property will update the internal linking between components.

InputRPM

Gets the input shaft RPM (revolutions per minute) of the component.

Declaration

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

Property Value

Type	Description
float

Remarks

This is a convenience property that converts the input angular velocity from rad/s to RPM for easier interpretation and debugging purposes.

Output

Gets or sets the powertrain component that receives output from this component.

Declaration

public PowertrainComponent Output { get; set; }

Property Value

Type	Description
PowertrainComponent

Remarks

This property establishes the connection to the next component in the powertrain chain. Setting this property will automatically update the bidirectional linking between components.

When setting a new output, the previous output connection (if any) will be automatically cleared, and the new output component will have its input reference set to this component.

Setting this property to null or the component itself will clear the output connection.

OutputRPM

Gets the output shaft RPM (revolutions per minute) of the component.

Declaration

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

Property Value

Type	Description
float

Remarks

This is a convenience property that converts the output angular velocity from rad/s to RPM for easier interpretation and debugging purposes.

Methods

CalculateOutputPowerInKW()

Calculates the current power output of this component in kilowatts.

Declaration

public float CalculateOutputPowerInKW()

Returns

Type	Description
float	Current power output in kilowatts (kW).

Remarks

Uses output torque and angular velocity for instantaneous power calculation.

ForwardStep(float, float, float)

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

Declaration

public virtual 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.

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.

GetPowerInKW(in float, in float)

Calculates power in kilowatts from torque and angular velocity values.

Declaration

public static float GetPowerInKW(in float torque, in float angularVelocity)

Parameters

Type	Name	Description
float	torque	Torque in N⋅m.
float	angularVelocity	Angular velocity in rad/s.

Returns

Type	Description
float	Power in kilowatts (kW).

Remarks

Same as TorqueToPowerInKW, alternative naming for readability in different contexts.

GetWorldPosition(VehicleController)

Gets the world position of this powertrain component for visualization purposes. Override in derived classes to provide component-specific positioning.

Declaration

public virtual Vector3 GetWorldPosition(VehicleController vc)

Parameters

Type	Name	Description
VehicleController	vc	The vehicle controller.

Returns

Type	Description
Vector3	World position of the component, or vehicle center if position cannot be determined.

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

Resolves a powertrain component link from persisted name + hash data. Tries name lookup first (stable across Unity versions); falls back to hash for legacy saved data. If both lookups fail, clears both fields so hot-path guards catch the missing link.

Declaration

protected static void LoadComponent(in VehicleController vc, ref PowertrainComponent component, ref string name, ref int hashCode)

Parameters

Type	Name	Description
VehicleController	vc
PowertrainComponent	component
string	name
int	hashCode

LoadComponentFromHash(in VehicleController, ref PowertrainComponent, ref int)

Loads a powertrain component reference from a stored name hash.

Declaration

protected static void LoadComponentFromHash(in VehicleController vc, ref PowertrainComponent component, ref int hashCode)

Parameters

Type	Name	Description
VehicleController	vc	The vehicle controller containing the powertrain components.
PowertrainComponent	component	Reference to the component variable to populate.
int	hashCode	The hash code of the component name to search for.

Remarks

This static utility method is used internally during component initialization to restore component connections based on stored name hashes. This system allows powertrain connections to persist through serialization.

If a component reference is null and a valid hash code exists, the method attempts to find and assign the corresponding component from the vehicle's powertrain.

PC_LogWarning(VehicleController, string)

Logs a warning message specific to this powertrain component.

Declaration

public void PC_LogWarning(VehicleController vc, string message)

Parameters

Type	Name	Description
VehicleController	vc	The vehicle controller that contains this component.
string	message	The warning message to log.

Remarks

Formats warning as: "name [TypeName] > message" for easier debugging.

PowerInKWToTorque(in float, in float)

Converts power in kilowatts and angular velocity to equivalent torque.

Declaration

public static float PowerInKWToTorque(in float angularVelocity, in float powerInKW)

Parameters

Type	Name	Description
float	angularVelocity	Angular velocity in rad/s.
float	powerInKW	Power in kilowatts (kW).

Returns

Type	Description
float	Equivalent torque in N⋅m.

Remarks

This static utility method calculates torque from power using the rearranged formula: Torque (N⋅m) = Power (W) / Angular Velocity (rad/s)

The method includes safety clamping for angular velocity to prevent division by zero or very small values that could cause numerical instabilities. When angular velocity is near zero, it's clamped to 1 rad/s for the calculation.

QueryAngularVelocity(float, float)

Queries and propagates angular velocity through the powertrain chain.

Declaration

public virtual 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.

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 virtual 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².

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 virtual float QueryReturnTorque()

Returns

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

QueryTorqueCapacity()

Maximum magnitude of torque this component can transmit to its input this substep. Infinite for rigid components; the clutch overrides it with its friction capacity so the engine cannot synchronize to the drivetrain faster than the clutch can transmit.

Declaration

public virtual float QueryTorqueCapacity()

Returns

Type	Description
float

TorqueToPowerInKW(in float, in float)

Converts torque and angular velocity to power output in kilowatts.

Declaration

public static float TorqueToPowerInKW(in float angularVelocity, in float torque)

Parameters

Type	Name	Description
float	angularVelocity	Angular velocity in rad/s.
float	torque	Torque in N⋅m.

Returns

Type	Description
float	Power output in kilowatts (kW).

Remarks

Formula: Power = Torque × Angular Velocity, converted to kW.

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.