Wheels Module Reference

Module defined in `lua/vehicle/wheels.lua`. This module manages the physical simulation, thermal state, and braking logic for wheels and non-tire rotators. It acts as the final interface between the [

Module defined in lua/vehicle/wheels.lua. This module manages the physical simulation, thermal state, and braking logic for wheels and non-tire rotators. It acts as the final interface between the Powertrain and the ground.

Class: Wheel Instance (`wd`)

These properties and methods are available on individual wheel/rotator objects within wheels.wheelRotators.

Physical Identification

name: Unique identifier (e.g., "FL").
cid: JBeam CID.
obj: Direct C++ object handle.
rotatorType: Classification (e.g., "wheel", "rotator").
wheelID: Physical index in the engine.
node1 / node2: The primary axle nodes defining the rotation axis.

Motion & Physics

angularVelocity / lastAngularVelocity: Current and previous rotation speed (rad/s).
wheelSpeed: Calculated linear speed at the tire surface (m/s).
propulsionTorque: Torque currently received from the powertrain (Nm).
brakingTorque: Total braking torque currently applied (Nm).
frictionTorque: Internal rolling friction (Nm).
downForce / downForceRaw: Filtered and raw vertical load (N).
peakForce: Maximum longitudinal force achieved (N).
slipEnergy: Energy dissipated through tire slip (Joules).
inertia: Rotational inertia of the wheel assembly (kg·m²).
radius: Static design radius (m).
dynamicRadius: Real-time radius accounting for load and deformation (m).
hubRadius: Radius of the rigid rim (m).
rayCount: Number of collision rays used for the tire simulation.

Tires & Surface

hasTire: Boolean flag for pneumatic tires.
isPunctured: True if the tire has a leak.
isTireDeflated: True if the tire is completely flat.
tireVolume: Internal air volume (m³).
tireWidth: Width of the tire tread (m).
softnessCoef: Material compliance factor.
treadCoef: Friction multiplier for the tread.
pressureGroup / pressureGroupId: JBeam pressure group association.
startingPressure: Initial inflation pressure (Pa).
**contactMaterialID1 / contactMaterialID2: Material IDs of the ground surfaces in contact.
contactDepth: Penetration into loose surfaces (m).
lastTreadContactNode: CID of the node currently making ground contact.

Braking & Thermals

brakeTorque / initialBrakeTorque: Design maximum and original torque (Nm).
parkingTorque: Torque applied by the handbrake (Nm).
brakeDiameter: Diameter of the brake disc/drum (m).
brakeMass: Thermal mass of the brake assembly (kg).
brakeType: Implementation string (e.g., "carbon-ceramic-vented-disc").
rotorMaterial / padMaterial: Material types for thermal lookup.
brakeSurfaceTemperature: Temperature at the friction interface (°C).
brakeCoreTemperature: Temperature of the brake bulk material (°C).
brakeMeltingPoint: Temperature at which the brakes fail (°C).
enableBrakeThermals: Boolean toggle for thermal simulation.
brakeThermalEfficiency: Efficiency multiplier (0-1) based on heat fade and glazing.
padGlazingFactor: Level of permanent pad damage from overheating (0-1).
brakeSpecHeat: Specific heat capacity (J/kg·K).
brakeVentingCoef: Airflow cooling efficiency.

ABS & Logic

hasABS: Boolean flag for ABS hardware.
lastABSCoef: Most recent ABS modulation factor (0-1).
slipRatioTarget: Optimal slip ratio for ABS control (e.g., 0.13).
lastSlip / lastSlipError: Current tire slip and deviation from target.
lastSideSlip: Angle of lateral tire slip (radians).

Variables

Variable	Type	Description
`wheelCount`	number	Count of active non-broken wheels.
`wheelRotatorCount`	number	Total count of all wheels and auxiliary rotators.
`wheelIDs`	table	Map of wheel names to their physical indices.
`wheelRotatorIDs`	table	Map of names to rotator indices.
`wheelTorque`	number	Total instantaneous propulsion torque (Nm).
`wheelPower`	number	Total instantaneous propulsion power (Watts).
`rotatorCount`	number	Count of auxiliary non-wheel rotators.
`brakeSurfaceTempOverride`	number	Manual override for all brake temperatures (DEBUG).
`treadNodeLookup`	table	Map of nodes to their parent wheel for tread physics.

Public API - Global

Function	Signature	Description
`wheels.setABSBehavior`	`(mode) / toggleABSBehavior() / resetABSBehavior()`	Configures the Anti-lock Braking System logic. `"realistic"` uses virtual airspeed estimation; `"arcade"` uses ground speed directly.
`wheels.scaleBrakeTorque`	`(factor)`	Universally scales the maximum braking torque for all wheels.
`wheels.setWheelBrakeUpdate`	`(name, noABS, withABS)`	Allows external controllers to inject custom braking math into specific wheels.
`wheels.setWheelRotatorType`	`(cid, type)`	Changes how a rotator is categorized for speedometer and traction logic.
`wheels.updateABSCoef`	`(dt)`	Internal math for calculating per-wheel ABS intervention factors.

Public API - Lifecycle & Updates

Function	Signature	Description
`wheels.init`	`() / initSecondStage() / reset() / resetSecondStage()`	Standard lifecycle hooks. Bootstraps indices, volumes, sides, and thermal constants. Returns `Result value.`.
`wheels.updateWheelVelocities`	`(dt)`	Physics step update. Calculates AVs, surface speeds, and handles virtual airspeed estimation logic.
`wheels.updateWheelTorques`	`(dt)`	Physics step update. Processes brake input, applies thermal efficiency losses, and syncs torques with the C++ engine.
`wheels.updateGFX`	`(dt) / updateThermalsGFX(dt)`	Graphics frame updates. Triggers tire puncture logic, particle spawning, and thermal radiation calculations.
`wheels.beamBroke`	`(id)`	Callback for structural failure. Immediately disables propulsion and braking for the affected wheel.
`wheels.nodeCollision`	`(cid, ...)`	Collision callback used to identify the node currently making ground contact for dynamic radius calculations.
`wheels.settingsChanged`	`()`	Refreshes default ABS behavior and thermal preferences from global game settings.
`module.initSounds`	`()`	Initializes sound resources.
`module.isPhysicsStepUsed`	`()`	Checks if physics step used. Returns `M.wheelRotatorCount > 0`.

Class: Wheel Instance (`wd`)

These properties and methods are available on individual wheel/rotator objects within wheels.wheelRotators.

Physical Identification

name: Unique identifier (e.g., "FL").
cid: JBeam CID.
obj: Direct C++ object handle.
rotatorType: Classification (e.g., "wheel", "rotator").
wheelID: Physical index in the engine.
node1 / node2: The primary axle nodes defining the rotation axis.

Motion & Physics

angularVelocity / lastAngularVelocity: Current and previous rotation speed (rad/s).
wheelSpeed: Calculated linear speed at the tire surface (m/s).
propulsionTorque: Torque currently received from the powertrain (Nm).
brakingTorque: Total braking torque currently applied (Nm).
frictionTorque: Internal rolling friction (Nm).
downForce / downForceRaw: Filtered and raw vertical load (N).
peakForce: Maximum longitudinal force achieved (N).
slipEnergy: Energy dissipated through tire slip (Joules).
inertia: Rotational inertia of the wheel assembly (kg·m²).
radius: Static design radius (m).
dynamicRadius: Real-time radius accounting for load and deformation (m).
hubRadius: Radius of the rigid rim (m).
rayCount: Number of collision rays used for the tire simulation.

Tires & Surface

hasTire: Boolean flag for pneumatic tires.
isPunctured: True if the tire has a leak.
isTireDeflated: True if the tire is completely flat.
tireVolume: Internal air volume (m³).
tireWidth: Width of the tire tread (m).
softnessCoef: Material compliance factor.
treadCoef: Friction multiplier for the tread.
pressureGroup / pressureGroupId: JBeam pressure group association.
startingPressure: Initial inflation pressure (Pa).
**contactMaterialID1 / contactMaterialID2: Material IDs of the ground surfaces in contact.
contactDepth: Penetration into loose surfaces (m).
lastTreadContactNode: CID of the node currently making ground contact.

Braking & Thermals

brakeTorque / initialBrakeTorque: Design maximum and original torque (Nm).
parkingTorque: Torque applied by the handbrake (Nm).
brakeDiameter: Diameter of the brake disc/drum (m).
brakeMass: Thermal mass of the brake assembly (kg).
brakeType: Implementation string (e.g., "carbon-ceramic-vented-disc").
rotorMaterial / padMaterial: Material types for thermal lookup.
brakeSurfaceTemperature: Temperature at the friction interface (°C).
brakeCoreTemperature: Temperature of the brake bulk material (°C).
brakeMeltingPoint: Temperature at which the brakes fail (°C).
enableBrakeThermals: Boolean toggle for thermal simulation.
brakeThermalEfficiency: Efficiency multiplier (0-1) based on heat fade and glazing.
padGlazingFactor: Level of permanent pad damage from overheating (0-1).
brakeSpecHeat: Specific heat capacity (J/kg·K).
brakeVentingCoef: Airflow cooling efficiency.

ABS & Logic

hasABS: Boolean flag for ABS hardware.
lastABSCoef: Most recent ABS modulation factor (0-1).
slipRatioTarget: Optimal slip ratio for ABS control (e.g., 0.13).
lastSlip / lastSlipError: Current tire slip and deviation from target.
lastSideSlip: Angle of lateral tire slip (radians).

Variables

Variable	Type	Description
`wheelCount`	number	Count of active non-broken wheels.
`wheelRotatorCount`	number	Total count of all wheels and auxiliary rotators.
`wheelIDs`	table	Map of wheel names to their physical indices.
`wheelRotatorIDs`	table	Map of names to rotator indices.
`wheelTorque`	number	Total instantaneous propulsion torque (Nm).
`wheelPower`	number	Total instantaneous propulsion power (Watts).
`rotatorCount`	number	Count of auxiliary non-wheel rotators.
`brakeSurfaceTempOverride`	number	Manual override for all brake temperatures (DEBUG).
`treadNodeLookup`	table	Map of nodes to their parent wheel for tread physics.

Public API - Global

Function	Signature	Description
`wheels.setABSBehavior`	`(mode) / toggleABSBehavior() / resetABSBehavior()`	Configures the Anti-lock Braking System logic. `"realistic"` uses virtual airspeed estimation; `"arcade"` uses ground speed directly.
`wheels.scaleBrakeTorque`	`(factor)`	Universally scales the maximum braking torque for all wheels.
`wheels.setWheelBrakeUpdate`	`(name, noABS, withABS)`	Allows external controllers to inject custom braking math into specific wheels.
`wheels.setWheelRotatorType`	`(cid, type)`	Changes how a rotator is categorized for speedometer and traction logic.
`wheels.updateABSCoef`	`(dt)`	Internal math for calculating per-wheel ABS intervention factors.

Public API - Lifecycle & Updates

Function	Signature	Description
`wheels.init`	`() / initSecondStage() / reset() / resetSecondStage()`	Standard lifecycle hooks. Bootstraps indices, volumes, sides, and thermal constants. Returns `Result value.`.
`wheels.updateWheelVelocities`	`(dt)`	Physics step update. Calculates AVs, surface speeds, and handles virtual airspeed estimation logic.
`wheels.updateWheelTorques`	`(dt)`	Physics step update. Processes brake input, applies thermal efficiency losses, and syncs torques with the C++ engine.
`wheels.updateGFX`	`(dt) / updateThermalsGFX(dt)`	Graphics frame updates. Triggers tire puncture logic, particle spawning, and thermal radiation calculations.
`wheels.beamBroke`	`(id)`	Callback for structural failure. Immediately disables propulsion and braking for the affected wheel.
`wheels.nodeCollision`	`(cid, ...)`	Collision callback used to identify the node currently making ground contact for dynamic radius calculations.
`wheels.settingsChanged`	`()`	Refreshes default ABS behavior and thermal preferences from global game settings.
`module.initSounds`	`()`	Initializes sound resources.
`module.isPhysicsStepUsed`	`()`	Checks if physics step used. Returns `M.wheelRotatorCount > 0`.

Wheels Module Reference

See Also

Class: Wheel Instance (`wd`)

Physical Identification

Motion & Physics

Tires & Surface

Braking & Thermals

ABS & Logic

Variables

Public API - Global

Public API - Lifecycle & Updates

On this page

Wheels Module Reference

See Also

Class: Wheel Instance (`wd`)

Physical Identification

Motion & Physics

Tires & Surface

Braking & Thermals

ABS & Logic

Variables

Public API - Global

Public API - Lifecycle & Updates

On this page