Class PowertrainComponent

Base class for all powertrain components. Components form a chain from EngineComponent (power source) to WheelComponent (power sink), which always outputs to WheelController. Each component adds its inertia to the system total, so higher inertia means slower spin-up and spin-down.

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

Inertia must be greater than 0. Renaming a component resets the outputs of every other PowertrainComponent that points at 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

0.001-0.01 is very responsive but easy to stall and can go unstable, 0.02-0.2 is balanced, 0.5+ is sluggish and hard to stall (heavy machinery). Typical: sports car 0.01-0.05, average car 0.02-0.1, truck 0.1-0.5. Must 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

Written by the solver each substep from the input component's output.

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

Accumulated during the forward torque pass.

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 lookup is stable across Unity versions; the legacy inputNameHash is not. Managed by the powertrain, not set by hand.

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

Primary persistence is inputName; this hash only resolves older saved data. Managed by the powertrain, not set by hand.

inputTorque

Current input torque in N⋅m.

Declaration

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

Field Value

Type	Description
float

Remarks

Written by the solver each substep from the input component's output.

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

Must be unique within a vehicle; links between components are resolved by it. Changing it resets the output connection of every component that pointed here.

outputAngularVelocity

Current output angular velocity in rad/s.

Declaration

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

Field Value

Type	Description
float

Remarks

Differs from inputAngularVelocity where the component applies a gear ratio.

outputInertia

Inertia handed to the output component in kg⋅m²: the upstream accumulation plus this component's own inertia.

Declaration

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

Field Value

Type	Description
float

Remarks

Written by ForwardStep(float, float, float) while an output component is connected, reflected by the gear ratio squared in components that have one. The downstream total is what QueryInertia(float) returns and is not stored.

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 lookup is stable across Unity versions; the legacy outputNameHash is not. Managed by the powertrain, not set by hand.

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

Primary persistence is outputName; this hash only resolves older saved data. Managed by the powertrain, not set by hand.

outputTorque

Current output torque in N⋅m.

Declaration

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

Field Value

Type	Description
float

Remarks

Differs from inputTorque where the component applies a gear ratio or a loss.

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

Drives sound positioning and the Scene view gizmo. Some components, differentials for one, derive the position from their outputs instead of using this value.

Properties

Damage

Gets or sets the damage level of the powertrain component.

Declaration

public float Damage { get; set; }

Property Value

Type	Description
float

Remarks

Clamped to 0-1 on set.

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

Assigning delegates to the source's Output setter, which owns the reciprocal link.

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

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

Assigning clears the previous output link and points the new target's Input back here. Null, or this component itself, clears the connection. A target that would close a loop is rejected with a warning.

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

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

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

Resolves only when the reference is null and the hash is non-zero. Clears the hash when no component matches it.

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

Torque (N⋅m) = Power (W) / Angular Velocity (rad/s). The divisor is floored at 1 rad/s so a stationary shaft does not divide by zero; the sign of angularVelocity is preserved.

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.

Overrides

VehicleComponent.VC_Disable(bool)

Remarks

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

VC_Initialize()

Initializes the powertrain component and establishes connections with other components.

Declaration

protected override void VC_Initialize()

Overrides

VehicleComponent.VC_Initialize()

Remarks

Floors inertia at MIN_INERTIA and resolves the input and output links from persisted names.

VC_SetDefaults()

Sets the component's properties to their default values.

Declaration

public override void VC_SetDefaults()

Overrides

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

VehicleComponent.VC_Validate(VehicleController)

Remarks

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

WouldCreateOutputCycle(PowertrainComponent)

True when linking candidate as an output would close a loop back onto this component. Walks both differential branches.

Declaration

protected bool WouldCreateOutputCycle(PowertrainComponent candidate)

Parameters

Type	Name	Description
PowertrainComponent	candidate

Returns

Type	Description
bool

See Also

EngineComponent

ClutchComponent

TransmissionComponent

DifferentialComponent

WheelComponent

Powertrain

VehicleComponent