Powertrain Module Reference

Module defined in `lua/vehicle/powertrain.lua`. This is the physical powertrain simulation engine, managing the interconnected tree of [Devices](/docs/api/ve/powertrain/FOLDER_OVERVIEW) (engines, transmissions,

Module defined in lua/vehicle/powertrain.lua. This is the physical powertrain simulation engine, managing the interconnected tree of Devices (engines, transmissions, differentials, shafts, and wheels).

Public API - Core Module

Standard hooks and dispatchers used by the vehicle engine.

Function	Signature	Description
`powertrain.init`	`() / reset()`	Primary initialization and reset. Builds the connection tree and calculates inertias.
`powertrain.update`	`(dt)`	Core physics loop: calculates leaf-to-root velocities followed by root-to-leaf torques.
`powertrain.updateGFX`	`(dt) / updateGFXLastStage(dt)`	Frame-rate updates for environment sync, damage checks, and GFX state.

Environment & Global State

Live environmental constants affecting powertrain performance.

Variable	Type	Description
`currentEnvPressure`	number	Atmospheric pressure in Pa.
`currentEnvTemperature`	number	Temperature in Kelvin.
`currentEnvTemperatureCelsius`	number	Temperature in °C.
`currentGravity`	number	Gravity magnitude (e.g., -9.81).
`stabilityCoef`	number	Physics stability factor (default 250).
`torqueReactionCoefs`	table	Array of torque reaction coefficients.
`cumulativeGearRatio`	number	Maximum gear ratio present in the tree.
`engineData`	table	Physical limits and reaction nodes for engines.

Public API - Device Management

Functions for finding and interacting with powertrain devices.

Function	Signature	Description
`powertrain.dumpsDeviceData`	`(device) / serializeDevicesInfo()`	Debug utilities for exporting the current powertrain state. Returns `serialize(serializeInfoRes)`.
`powertrain.getDevice`	`(name)`	Returns the device object with the specified name.
`powertrain.getDevicesByCategory`	`(category) / getDevicesByType(type)`	Returns an array of devices matching the criteria (e.g., `"engine"`, `"differential"`).
`powertrain.getOrderedDevices`	`()`	Returns the list of devices in leaf-to-root update order.
`powertrain.getPoweredWheelNames`	`()`	Returns a map of wheel names to their propulsion device names.
`powertrain.getPropulsionDeviceForWheel`	`(name) / getPropulsionDeviceForDevice(device)`	Traverses the tree to find the root engine for a specific component. Returns `nil --didn't find anything...`.
`powertrain.getChildWheels`	`(deviceName)`	Returns a list of all wheels connected downstream of a device.
`powertrain.getHydraulicConsumer`	`(name)`	Locates a device using hydraulic power (e.g., pumps, cylinders).
`powertrain.getPartCondition`	`(partName)`	Returns part condition data. Returns `table`.
`powertrain.setPartCondition`	`(partTypeData, odometer, integrity, visual)`	Sets the condition for powertrain parts.
`powertrain.getEngineSoundID`	`()`	Generates a unique numeric ID for engine sound registration.
`powertrain.setDeviceMode`	`(name, mode) / toggleDeviceMode(name)`	Changes the operating mode of a device (e.g., locking a differential). Returns `newMode`.
`powertrain.breakDevice`	`(device)`	Manually forces a device into a broken state and snaps associated JBeam beams.

Brake & Energy Systems

Engine Specific (ICE)

These functions specifically target combustion engine behaviors.

Public API - Exhaust & Sound

Function	Signature	Description
`powertrain.updateSounds`	`(dt)`	Main dispatcher for audio simulation updates.

Public API - UI & Interface

Function	Signature	Description
`powertrain.sendDeviceTree`	`()`	Exports the physical topology of the powertrain to the UI.
`powertrain.updateSimpleControlButtons`	`()`	Refreshes UI button states for powertrain-linked features.

Public API - Logic & State Management

Function	Signature	Description
`powertrain.getState`	`() / setState(state)`	Interface for saving/restoring logical state.
`powertrain.publishStateEvent`	`(event) / triggerStateEvent(event)`	Dispatchers for logic-triggered events (e.g., differential lock changes).

Wheels Reference

Access via powertrain.wheels[wheelName] (e.g., FL, FR, RL, RR).

Core Properties

cid: BeamNode ID.
obj: Physical C++ wheel object.
radius / dynamicRadius: Static and live tire radius (m).
angularVelocity: Current rotation speed (rad/s).
propulsionTorque: Current torque from engine (Nm).
brakingTorque: Current torque from brakes (Nm).
downForce: Vertical load on the tire (N).
isBroken / isPunctured / isTireDeflated: Status flags.

Thermals

brakeCoreTemperature: Temperature of the brake disc (°C).
brakeSurfaceTemperature: Temperature of the pad/surface interface (°C).
brakeMeltingPoint: Thermal failure threshold.

Generic Device Structure

All powertrain devices (Engines, Transmissions, Drivelines) share these properties:

Properties

name: Unique identifier.
type: Device implementation (e.g., "combustionEngine", "differential").
mode: Current operating state.
cumulativeGearRatio: Total ratio from this device to the wheels.
isBroken / isPhysicallyDisconnected: Operational flags.
children: List of downstream devices.

Public API - Methods

device:calculateInertia(): Recalculates downstream mass.
device:onBreak(): Internal callback for structural failure.
device:setMode(mode): External interface to change behavior.
device:applyDeformGroupDamage(damage): Visual damage integration.

Hooks

Function	Signature	Description
`module.initSounds`	`()`	Initializes sound resources.
`module.resetSounds`	`()`	Resets sound state.
`module.onCouplerFound`	`(nodeId, obj2id, obj2nodeId, nodeDist)`	Callback for coupler found event.
`module.onCouplerAttached`	`(nodeId, obj2id, obj2nodeId, attachSpeed, attachEnergy)`	Callback for coupler attached event.
`module.onCouplerDetached`	`(nodeId, obj2id, obj2nodeId, breakForce)`	Callback for coupler detached event.
`module.calculateTreeInertia`	`()`	iterate starting at the wheels for various calculations throughout the tree(s)
`module.toggleDefaultDiffs`	`()`	Toggles default diffs.
`module.getAllWheelPropulsionDevices`	`()`	Returns the all wheel propulsion devices. Returns `propulsionDevices`.
`module.setVehiclePath`	`(path)`	Sets the vehicle path.
`module.getStateEvents`	`()`	Returns the state events. Returns `stateEvents`.
`module.isPhysicsStepUsed`	`()`	Checks if physics step used. Returns `hasPowertrain`.

Public API - Core Module

Standard hooks and dispatchers used by the vehicle engine.

Function	Signature	Description
`powertrain.init`	`() / reset()`	Primary initialization and reset. Builds the connection tree and calculates inertias.
`powertrain.update`	`(dt)`	Core physics loop: calculates leaf-to-root velocities followed by root-to-leaf torques.
`powertrain.updateGFX`	`(dt) / updateGFXLastStage(dt)`	Frame-rate updates for environment sync, damage checks, and GFX state.

Environment & Global State

Live environmental constants affecting powertrain performance.

Variable	Type	Description
`currentEnvPressure`	number	Atmospheric pressure in Pa.
`currentEnvTemperature`	number	Temperature in Kelvin.
`currentEnvTemperatureCelsius`	number	Temperature in °C.
`currentGravity`	number	Gravity magnitude (e.g., -9.81).
`stabilityCoef`	number	Physics stability factor (default 250).
`torqueReactionCoefs`	table	Array of torque reaction coefficients.
`cumulativeGearRatio`	number	Maximum gear ratio present in the tree.
`engineData`	table	Physical limits and reaction nodes for engines.

Public API - Device Management

Functions for finding and interacting with powertrain devices.

Function	Signature	Description
`powertrain.dumpsDeviceData`	`(device) / serializeDevicesInfo()`	Debug utilities for exporting the current powertrain state. Returns `serialize(serializeInfoRes)`.
`powertrain.getDevice`	`(name)`	Returns the device object with the specified name.
`powertrain.getDevicesByCategory`	`(category) / getDevicesByType(type)`	Returns an array of devices matching the criteria (e.g., `"engine"`, `"differential"`).
`powertrain.getOrderedDevices`	`()`	Returns the list of devices in leaf-to-root update order.
`powertrain.getPoweredWheelNames`	`()`	Returns a map of wheel names to their propulsion device names.
`powertrain.getPropulsionDeviceForWheel`	`(name) / getPropulsionDeviceForDevice(device)`	Traverses the tree to find the root engine for a specific component. Returns `nil --didn't find anything...`.
`powertrain.getChildWheels`	`(deviceName)`	Returns a list of all wheels connected downstream of a device.
`powertrain.getHydraulicConsumer`	`(name)`	Locates a device using hydraulic power (e.g., pumps, cylinders).
`powertrain.getPartCondition`	`(partName)`	Returns part condition data. Returns `table`.
`powertrain.setPartCondition`	`(partTypeData, odometer, integrity, visual)`	Sets the condition for powertrain parts.
`powertrain.getEngineSoundID`	`()`	Generates a unique numeric ID for engine sound registration.
`powertrain.setDeviceMode`	`(name, mode) / toggleDeviceMode(name)`	Changes the operating mode of a device (e.g., locking a differential). Returns `newMode`.
`powertrain.breakDevice`	`(device)`	Manually forces a device into a broken state and snaps associated JBeam beams.

Brake & Energy Systems

Engine Specific (ICE)

These functions specifically target combustion engine behaviors.

Public API - Exhaust & Sound

Function	Signature	Description
`powertrain.updateSounds`	`(dt)`	Main dispatcher for audio simulation updates.

Public API - UI & Interface

Function	Signature	Description
`powertrain.sendDeviceTree`	`()`	Exports the physical topology of the powertrain to the UI.
`powertrain.updateSimpleControlButtons`	`()`	Refreshes UI button states for powertrain-linked features.

Public API - Logic & State Management

Function	Signature	Description
`powertrain.getState`	`() / setState(state)`	Interface for saving/restoring logical state.
`powertrain.publishStateEvent`	`(event) / triggerStateEvent(event)`	Dispatchers for logic-triggered events (e.g., differential lock changes).

Wheels Reference

Access via powertrain.wheels[wheelName] (e.g., FL, FR, RL, RR).

Core Properties

cid: BeamNode ID.
obj: Physical C++ wheel object.
radius / dynamicRadius: Static and live tire radius (m).
angularVelocity: Current rotation speed (rad/s).
propulsionTorque: Current torque from engine (Nm).
brakingTorque: Current torque from brakes (Nm).
downForce: Vertical load on the tire (N).
isBroken / isPunctured / isTireDeflated: Status flags.

Thermals

brakeCoreTemperature: Temperature of the brake disc (°C).
brakeSurfaceTemperature: Temperature of the pad/surface interface (°C).
brakeMeltingPoint: Thermal failure threshold.

Generic Device Structure

All powertrain devices (Engines, Transmissions, Drivelines) share these properties:

Properties

name: Unique identifier.
type: Device implementation (e.g., "combustionEngine", "differential").
mode: Current operating state.
cumulativeGearRatio: Total ratio from this device to the wheels.
isBroken / isPhysicallyDisconnected: Operational flags.
children: List of downstream devices.

Public API - Methods

device:calculateInertia(): Recalculates downstream mass.
device:onBreak(): Internal callback for structural failure.
device:setMode(mode): External interface to change behavior.
device:applyDeformGroupDamage(damage): Visual damage integration.

Hooks

Function	Signature	Description
`module.initSounds`	`()`	Initializes sound resources.
`module.resetSounds`	`()`	Resets sound state.
`module.onCouplerFound`	`(nodeId, obj2id, obj2nodeId, nodeDist)`	Callback for coupler found event.
`module.onCouplerAttached`	`(nodeId, obj2id, obj2nodeId, attachSpeed, attachEnergy)`	Callback for coupler attached event.
`module.onCouplerDetached`	`(nodeId, obj2id, obj2nodeId, breakForce)`	Callback for coupler detached event.
`module.calculateTreeInertia`	`()`	iterate starting at the wheels for various calculations throughout the tree(s)
`module.toggleDefaultDiffs`	`()`	Toggles default diffs.
`module.getAllWheelPropulsionDevices`	`()`	Returns the all wheel propulsion devices. Returns `propulsionDevices`.
`module.setVehiclePath`	`(path)`	Sets the vehicle path.
`module.getStateEvents`	`()`	Returns the state events. Returns `stateEvents`.
`module.isPhysicsStepUsed`	`()`	Checks if physics step used. Returns `hasPowertrain`.

Powertrain Module Reference

See Also

Public API - Core Module

Environment & Global State

Public API - Device Management

Brake & Energy Systems

Engine Specific (ICE)

Public API - Exhaust & Sound

Public API - UI & Interface

Public API - Logic & State Management

Wheels Reference

Core Properties

Thermals

Generic Device Structure

Properties

Public API - Methods

Hooks

On this page

Powertrain Module Reference

See Also

Public API - Core Module

Environment & Global State

Public API - Device Management

Brake & Energy Systems

Engine Specific (ICE)

Public API - Exhaust & Sound

Public API - UI & Interface

Public API - Logic & State Management

Wheels Reference

Core Properties

Thermals

Generic Device Structure

Properties

Public API - Methods

Hooks

On this page