Class EngineComponent

Engine component that simulates internal combustion engines (ICE) or electric motors. Provides power to the drivetrain based on throttle input, RPM, and power curves.

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

The EngineComponent is the primary power source of the vehicle powertrain system. It converts throttle input into rotational torque through configurable power curves, handles engine starting/stopping, idle control, rev limiting, and various engine behaviors like forced induction.

Key features include: - Support for both ICE and electric motor configurations with different behaviors - Realistic power curve simulation based on RPM and throttle position - Engine starting system with starter motor simulation for ICE engines - Rev limiter to prevent over-revving and engine damage - Idle RPM control to maintain minimum engine speed - Forced induction support (turbocharger/supercharger) for increased power - Power modifier system for traction control and other assistance systems

ICE engines feature realistic starting behavior, can stall at low RPM, and require ignition. Electric motors provide instant torque, can run in reverse, and cannot stall. The power output is calculated using the power curve multiplied by maximum power and various modifiers.

Fields

MIN_REV_LIMITER_RPM

Minimum allowed rev limiter RPM to prevent division by zero in physics calculations.

Declaration
public const float MIN_REV_LIMITER_RPM = 100
Field Value
Type Description
float

RPM_TO_ANGULAR_VELOCITY

Conversion factor from RPM to angular velocity in rad/s (2π/60).

Declaration
public const float RPM_TO_ANGULAR_VELOCITY = 0.10471976
Field Value
Type Description
float

WATTS_TO_KILOWATTS

Conversion factor from watts to kilowatts (1/1000).

Declaration
public const float WATTS_TO_KILOWATTS = 0.001
Field Value
Type Description
float

autoStartOnThrottle

Enables automatic engine starting when throttle input is detected. Only applies to ICE engines - electric motors don't require starting.

Declaration
[Tooltip("If true, the starter runs for [starterRunTime] seconds if the engine receives any throttle input.")]
public bool autoStartOnThrottle
Field Value
Type Description
bool
Remarks

When enabled, applying throttle to a stopped ICE engine will automatically engage the starter motor for the configured starter run time. This provides convenient gameplay behavior without requiring separate ignition key input.

Enable for: Arcade-style games, simplified controls, automatic vehicle behavior. Disable for: Realistic simulation, manual ignition control, race start procedures.

calculateTorqueDelegate

Custom delegate for calculating engine torque output.

Declaration
[Tooltip("Assign your own delegate to use a different type of torque calculation.")]
public EngineComponent.CalculateTorque calculateTorqueDelegate
Field Value
Type Description
EngineComponent.CalculateTorque
Remarks

Assign a custom delegate to override the default torque calculation behavior. By default, the engine uses CalculateTorqueICE for internal combustion engines or CalculateTorqueElectric for electric motors. Override this for specialized engine behaviors or custom powerplant simulations.

damageLossIncrease

Additional engine loss percentage added at full damage. Increases engine braking and parasitic losses.

Declaration
[Range(0, 0.5)]
[Tooltip("Additional engine loss percentage at full damage. Increases engine braking.")]
public float damageLossIncrease
Field Value
Type Description
float

damagePowerReduction

Maximum power reduction at full damage (0-1). 0.8 means 80% power loss when damage=1.

Declaration
[Range(0, 1)]
[Tooltip("Maximum power reduction at full damage (0-1). 0.8 = 80% power loss at damage=1.")]
public float damagePowerReduction
Field Value
Type Description
float

engineBrakingRpmRise

How strongly off-throttle engine-braking torque rises with RPM (0-1). At 0, drag torque is roughly constant across the rev range (original behaviour). At 1, drag torque grows linearly with RPM, approximating real engine friction/pumping (FMEP) which increases with engine speed.

Declaration
[Range(0, 1)]
[Tooltip("How strongly off-throttle engine braking rises with RPM. 0 = constant drag torque across the rev range (original behaviour, presets unchanged). 1 = drag torque grows linearly with RPM, matching the rising friction/pumping of a real engine, so engine braking is stronger near the redline.")]
public float engineBrakingRpmRise
Field Value
Type Description
float

engineLossPercent

Engine parasitic losses as a percentage of maximum power, ranging from 0 (no losses) to 1 (100% loss).

Declaration
[Range(0, 1)]
[Tooltip("Loss power (pumping, friction losses) is calculated as the percentage of maxPower.\r\nShould be between 0 and 1 (100%).")]
public float engineLossPercent
Field Value
Type Description
float
Remarks

Represents internal friction, pumping losses, and accessory drag that oppose engine rotation. These losses increase with RPM and reduce net power output, affecting deceleration characteristics when off-throttle and engine braking effectiveness.

Typical values: - 0.15-0.20: High-efficiency modern engines - 0.20-0.30: Average engines (most vehicles) - 0.30-0.40: Older engines or those with high accessory loads

Higher values create stronger engine braking and slower coast-down. Lower values provide more efficient power delivery but reduce engine braking effectiveness.

engineType

Engine type. ICE (Internal Combustion Engine) supports features such as starter, stalling, etc. Electric engine (motor) can run in reverse, cannot be stalled and does not use starter.

Declaration
[Tooltip("Engine type. ICE (Internal Combustion Engine) supports features such as starter, stalling, etc.\r\nElectric engine (motor) can run in reverse, can not be stalled and does not use starter.")]
[ShowInTelemetry(NaN, NaN, null, null, 1)]
[ShowInSettings]
public EngineComponent.EngineType engineType
Field Value
Type Description
EngineComponent.EngineType

exhaustPosition

Position of the exhaust in local space relative to the vehicle transform.

Declaration
[Tooltip("Position of the exhaust relative to the vehicle. Turn on gizmos to see the marker.")]
public Vector3 exhaustPosition
Field Value
Type Description
Vector3
Remarks

Used for exhaust particle effects, sound positioning, and visual representation. Shown as a gizmo in Scene view when debug gizmos are enabled.

flyingStartEnabled

If true, the engine will be started immediately, without running the starter, when the vehicle is enabled. Sets engine angular velocity to idle angular velocity.

Declaration
[Tooltip("If true the engine will be started immediately, without running the starter, when the vehicle is enabled.\r\nSets engine angular velocity to idle angular velocity.")]
public bool flyingStartEnabled
Field Value
Type Description
bool

forcedInduction

Turbocharger or supercharger.

Declaration
[Tooltip("Turbocharger or supercharger.")]
public EngineComponent.ForcedInduction forcedInduction
Field Value
Type Description
EngineComponent.ForcedInduction

generatedPower

Power generated by the engine in kW

Declaration
[ShowInTelemetry(0, 500, "0.0", "kW", 1)]
[NonSerialized]
[Tooltip("Power generated by the engine in kW")]
public float generatedPower
Field Value
Type Description
float

idleRPM

Target idle RPM that the idle control system maintains when the engine is running with no throttle input.

Declaration
[SerializeField]
[Tooltip("RPM at which idler circuit will try to keep RPMs when there is no input.")]
public float idleRPM
Field Value
Type Description
float
Remarks

The idle control system automatically adjusts throttle to maintain this RPM when the engine is in idle. This prevents stalling and ensures smooth operation at low speeds. Only applies to ICE engines; electric motors can operate at 0 RPM without stalling.

Typical values: - 600-800 RPM: Modern fuel-injected engines (smooth, efficient idle) - 800-1000 RPM: Older carbureted engines or performance engines - 1000-1200 RPM: High-performance engines with aggressive camshafts - 1200+ RPM: Racing engines or high-idle applications

Lower idle RPM improves fuel efficiency and reduces noise but may cause rough idle or stalling if set too low. Higher idle RPM ensures stability but increases fuel consumption. The idle RPM should always be significantly higher than stallRPM for stable operation.

ignition

Ignition switch state. When false, the engine cannot generate power even if running.

Declaration
public bool ignition
Field Value
Type Description
bool
Remarks

Controls whether the engine can produce power. For ICE engines, turning ignition off while running will cut fuel delivery and cause the engine to stop. For electric motors, this controls the electrical power supply. Use StartEngine() and StopEngine() methods for proper engine control rather than directly toggling this field.

isRunning

Is the engine currently running? Requires ignition to be enabled and engine RPM above the stall RPM.

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

load

Current load of the engine, based on the power produced.

Declaration
[NonSerialized]
[ShowInTelemetry(0, 1, "0.00", null, 1)]
public float load
Field Value
Type Description
float

maxPower

Maximum power output of the engine in kilowatts (kW). This represents the peak power the engine can produce at optimal RPM.

Declaration
[ShowInSettings("Max. Power", 20, 400, 10)]
[Tooltip("Maximum engine power in [kW].")]
public float maxPower
Field Value
Type Description
float
Remarks

The actual power output varies based on RPM according to the power curve. This maximum value is multiplied by the power curve coefficient to determine instantaneous power at any given RPM and throttle position.

Typical values: Small car: 60-100 kW (80-130 HP) Mid-size car: 120-180 kW (160-240 HP) Sports car: 200-400 kW (270-530 HP) Truck/SUV: 150-300 kW (200-400 HP)

Higher values provide more acceleration and top speed but may require careful tuning of traction control and stability systems to maintain realistic behavior.

onRevLimiter

Called when engine hits rev limiter.

Declaration
[Tooltip("Called when engine hits rev limiter.")]
public UnityEvent onRevLimiter
Field Value
Type Description
UnityEvent

onStart

Called when engine is started.

Declaration
[Tooltip("Called when engine is started.")]
public UnityEvent onStart
Field Value
Type Description
UnityEvent

onStop

Called when engine is stopped.

Declaration
[Tooltip("Called when engine is stopped.")]
public UnityEvent onStop
Field Value
Type Description
UnityEvent

powerCurve

Power curve with RPM range [0,1] on the X axis and power coefficient [0,1] on Y axis. Both values are represented as percentages and should be in the 0 to 1 range. Power coefficient is multiplied by maxPower to get the final power at a given RPM.

Declaration
[Tooltip("Power curve with RPM range [0,1] on the X axis and power coefficient [0,1] on Y axis.\r\nBoth values are represented as percentages and should be in 0 to 1 range.\r\nPower coefficient is multiplied by maxPower to get the final power at given RPM.")]
public AnimationCurve powerCurve
Field Value
Type Description
AnimationCurve

powerModifiers

List of callbacks that influence engine power. Examples would be traction control that reduces power (returns less than 1) or forced induction which increases power (returns more than 1). Can also be used by modules to reduce engine power in certain situations. The final power modifier value is calculated by multiplying return values of all callbacks.

Declaration
[Tooltip("List of callbacks that influence engine power. Examples would be traction control which\r\nreduces power (returns less than 1) or forced induction which increases power (returns more than 1).\r\nCan also be used by modules to reduce engine power in certain situations.\r\nFinal power modifier value is calculated by multiplying return values of all callbacks.")]
[NonSerialized]
public List<EngineComponent.PowerModifier> powerModifiers
Field Value
Type Description
List<EngineComponent.PowerModifier>

revLimiterActive

Is the engine currently hitting the rev limiter?

Declaration
[NonSerialized]
[ShowInTelemetry(NaN, NaN, null, null, 1)]
[Tooltip("Is the engine currently hitting the rev limiter?")]
public bool revLimiterActive
Field Value
Type Description
bool

revLimiterCutoffDuration

If engine RPM rises above revLimiterRPM, how long should fuel cutoff last? Higher values make hitting rev limiter more rough and choppy.

Declaration
[Tooltip("If engine RPM rises above revLimiterRPM, how long should fuel cutoff last?\r\nHigher values make hitting rev limiter more rough and choppy.")]
public float revLimiterCutoffDuration
Field Value
Type Description
float

revLimiterRPM

Engine RPM at which rev limiter activates.

Declaration
[Tooltip("Engine RPM at which rev limiter activates.")]
public float revLimiterRPM
Field Value
Type Description
float

rpmPercent

RPM as a percentage of maximum RPM.

Declaration
[NonSerialized]
public float rpmPercent
Field Value
Type Description
float

runModifiers

List of callbacks that influence if the engine can run. All modifiers have to return true for the engine to run.

Declaration
[NonSerialized]
[Tooltip("List of callbacks that influence if the engine can run. All modifiers have to return true for the engine to run.")]
public List<EngineComponent.CanRunModifier> runModifiers
Field Value
Type Description
List<EngineComponent.CanRunModifier>

stallRPM

Minimum RPM below which the ICE engine will stall and stop running. Set to 0 to disable stalling.

Declaration
[SerializeField]
[Tooltip("RPM at which the engine will stall. Set to 0 to disable stalling.")]
public float stallRPM
Field Value
Type Description
float
Remarks

When engine RPM drops below this threshold, the engine will stall and require restarting. This simulates the behavior of real ICE engines that cannot maintain combustion at very low speeds. Electric motors are not affected by stalling and can operate at any RPM including zero.

Typical values: - 300-400 RPM: Modern engines with good low-speed stability - 400-500 RPM: Older or performance engines - 0 RPM: Disable stalling for arcade-style gameplay

Stall RPM should always be significantly lower than idle RPM (typically 400-600 RPM below) to provide a safety margin. If stall RPM is too close to idle RPM, the engine may stall during normal idle operation or low-speed maneuvering.

startDuration

Duration in seconds that the starter motor operates when starting the engine.

Declaration
[Tooltip("Duration in seconds that the starter motor operates when starting the engine.")]
public float startDuration
Field Value
Type Description
float
Remarks

Determines how long the starter motor cranks the engine during the starting sequence. The starter applies torque to spin up the engine from rest to idle RPM. This duration must be long enough for the engine to overcome its inertia and internal losses.

Typical values: - 0.2-0.4 seconds: Quick-starting modern engines with low inertia - 0.4-0.6 seconds: Average engines - 0.6-1.0 seconds: Heavy engines or those with high inertia

If the starter duration is too short, the engine may fail to reach idle RPM and stall immediately after starting. If too long, the starting sequence will feel sluggish. The starter torque is automatically calculated based on engine inertia and this duration. Minimum value is clamped to 0.1 seconds to prevent excessive torque impulses.

starterActive

Is the starter currently active?

Declaration
[NonSerialized]
[ShowInTelemetry(NaN, NaN, null, null, 1)]
[Tooltip("Is the starter currently active?")]
public bool starterActive
Field Value
Type Description
bool

throttleLossFactorResponseRate

Rate (1/s) at which the throttle-position loss factor approaches its target. Higher = snappier engine-braking transition off-throttle.

Declaration
[Range(0.5, 50)]
[Tooltip("Rate (1/s) at which the throttle-position loss factor approaches its target. The pumping-loss curve jumps ~20x when throttle is fully released, which propagates through a locked diff to wheels as a sudden negative torque step that destabilises the free-rolling friction solver. Smoothing across frames keeps the engine-drag transition gradual. Default 8 = ~0.125s time constant (perceptually instant). Raise toward 20+ if engine braking feels soggy.")]
public float throttleLossFactorResponseRate
Field Value
Type Description
float

throttlePosition

Engine throttle position. 0 for no throttle and 1 for full throttle.

Declaration
[NonSerialized]
[ShowInTelemetry(0, 1, "0.00", null, 1)]
public float throttlePosition
Field Value
Type Description
float

Properties

EstimatedPeakPower

Peak power as calculated from the power curve. If the power curve peaks at Y=1, the peak power will equal max power field value. After changing power, power curve or RPM range call UpdatePeakPowerAndTorque() to get to update the value.

Declaration
public float EstimatedPeakPower { get; }
Property Value
Type Description
float

EstimatedPeakPowerRPM

RPM at which the peak power is achieved. After changing power, power curve or RPM range call UpdatePeakPowerAndTorque() to get to update the value.

Declaration
public float EstimatedPeakPowerRPM { get; }
Property Value
Type Description
float

EstimatedPeakTorque

Peak torque value as calculated from the power curve. After changing power, power curve or RPM range call UpdatePeakPowerAndTorque() to get to update the value.

Declaration
public float EstimatedPeakTorque { get; }
Property Value
Type Description
float

EstimatedPeakTorqueRPM

RPM at which the engine achieves the peak torque, calculated from the power curve. After changing power, power curve or RPM range call UpdatePeakPowerAndTorque() to get to update the value.

Declaration
public float EstimatedPeakTorqueRPM { get; }
Property Value
Type Description
float

IsStalled

Is the engine stalled or stalling? ICE engine only.

Declaration
[ShowInTelemetry(NaN, NaN, null, null, 1)]
public bool IsStalled { get; }
Property Value
Type Description
bool

Methods

CalculateTorqueElectric(float, float)

Calculates output torque for electric motor powerplants.

Declaration
public float CalculateTorqueElectric(float angularVelocity, float dt)
Parameters
Type Name Description
float angularVelocity

Current engine angular velocity in rad/s.
float dt

Time step for the calculation in seconds.
Returns
Type Description
float

Total torque output in N⋅m, including generated power and resistive losses.
Remarks

Electric motors provide instant torque response without the need for a starter or idle system. Unlike ICE engines, they can operate bidirectionally and generate maximum torque from zero RPM.

The calculation considers: - Throttle position for power demand - Power modifiers for traction control and other systems - Velocity-dependent losses that increase with RPM - Ignition state (on/off control)

Power output is reduced during transmission shifting to prevent torque spikes. The motor characteristics provide smooth, linear power delivery ideal for electric vehicles and arcade-style gameplay.

CalculateTorqueICE(float, float)

Calculates output torque for internal combustion engine (ICE) powerplants.

Declaration
public float CalculateTorqueICE(float angularVelocity, float dt)
Parameters
Type Name Description
float angularVelocity

Current engine angular velocity in rad/s.
float dt

Time step for the calculation in seconds.
Returns
Type Description
float

Total torque output in N⋅m, including generated power, losses, starter motor, and idle correction.
Remarks

Implements ICE simulation: power curve torque, idle control, starter motor, rev limiter, stall logic, friction/pumping losses, and forced induction. Throttle is auto-managed during shifting and starting. Loss torque provides engine braking off-throttle.

GetPeakPower(out float, out float)

Calculates the peak power output and the RPM at which it occurs from the power curve.

Declaration
public void GetPeakPower(out float peakPower, out float peakPowerRpm)
Parameters
Type Name Description
float peakPower

Output parameter receiving the maximum power value in kW.
float peakPowerRpm

Output parameter receiving the RPM at which peak power occurs.
Remarks

Samples the power curve to find the highest coefficient value, then multiplies by maxPower to determine the actual peak power output. The corresponding X-axis position indicates the RPM percentage where this peak occurs.

The peak power calculation accounts for: - Power curve maximum Y value (coefficient) - Maximum power rating (maxPower field) - Forced induction multiplier if enabled

For most engines, peak power occurs near the upper end of the RPM range but before the rev limiter. This represents the optimal RPM for maximum velocity and is used for performance metrics display and transmission shift point calculations.

GetPeakTorque(out float, out float)

Calculates the peak torque output and the RPM at which it occurs from the power curve.

Declaration
public void GetPeakTorque(out float peakTorque, out float peakTorqueRpm)
Parameters
Type Name Description
float peakTorque

Output parameter receiving the maximum torque value in N⋅m.
float peakTorqueRpm

Output parameter receiving the RPM at which peak torque occurs.
Remarks

Samples the power curve at multiple points between idle and rev limiter RPM to find the peak torque. For each sample point, torque is calculated from power using the relationship: Torque = Power / Angular Velocity

The peak torque calculation accounts for: - Power curve shape and coefficients - Maximum power rating - Forced induction multiplier if enabled

Peak torque typically occurs at lower RPM than peak power in ICE engines, representing the point where the engine produces maximum force for acceleration. This is used for informational display and transmission tuning.

GetWorldPosition(VehicleController)

Gets the world position of the engine component.

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

The vehicle controller.
Returns
Type Description
Vector3

Engine position in world space.
Overrides

IntegrateDownwards(float, WheelControllerGroup)

Main physics update method that solves engine dynamics and propagates torque through the powertrain.

Declaration
public void IntegrateDownwards(float DeltaTime, WheelControllerGroup group = null)
Parameters
Type Name Description
float DeltaTime

Physics time step in seconds.
WheelControllerGroup group
Remarks

Called each physics frame by Powertrain.VC_FixedUpdate(). Updates engine state, queries wheel velocities, calculates torque, propagates through drivetrain, and integrates RPM. Uses semi-implicit integration with generated, reaction, and return torques. Do not call manually.

StartEngine()

Starts the engine, engaging the starter motor if needed for ICE engines.

Declaration
public void StartEngine()
Remarks

For ICE engines: - If flyingStartEnabled is true, immediately sets RPM to idle speed - Otherwise, initiates the starter motor sequence to crank the engine - The starter applies torque for the configured startDuration - Engine will stall if starter duration is insufficient to reach idle RPM

For electric motors: - Starts instantly without any starter sequence - Immediately ready to produce torque at any RPM

Starting is prevented if the engine is fully damaged (Damage >= 1.0). The onStart UnityEvent is invoked to allow sound effects and other responses.

StartStopEngine()

Toggles the engine between running and stopped states.

Declaration
public void StartStopEngine()
Remarks

If the engine is currently running, it will be stopped. If stopped, it will be started. For ICE engines, starting may involve a starter motor sequence unless flyingStartEnabled is true. Electric motors start instantly. This provides a convenient way to toggle engine state with a single method call.

StopEngine()

Stops the engine and resets all engine operating parameters.

Declaration
public void StopEngine()
Remarks

Stopping the engine performs the following actions: - Disables ignition to cut power generation - Stops any running starter motor coroutine - Resets throttle position, power modifiers, and load to zero - Clears starter torque - Invokes the onStop UnityEvent for audio/visual feedback

The engine will naturally decelerate to zero RPM based on drivetrain inertia and losses. For ICE engines, this simulates the engine winding down after ignition is cut. The engine remains stopped until StartEngine() is called again or autoStartOnThrottle initiates a restart.

UpdatePeakPowerAndTorque()

Recalculates peak power and torque values from the current power curve and engine settings.

Declaration
public void UpdatePeakPowerAndTorque()
Remarks

Call after modifying power curve, max power, rev limiter, or forced induction. Automatically called during initialization; only needed for runtime changes.

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_Enable(bool)

Enables the component and starts updates. Override to add component-specific enable logic.

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

True if called by parent component or LOD system
Returns
Type Description
bool

True if successfully enabled, false otherwise
Overrides
Remarks

Will initialize the component if not already initialized. Components disabled by LOD system will track the parent caller to prevent manual enabling while LOD is controlling state.

VC_Initialize()

Initializes the powertrain component and establishes connections with other components.

Declaration
protected override void VC_Initialize()
Overrides
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
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.