Class VehicleDynamicsSystem

Namespace

LibreRally.Vehicle.Physics

Assembly

LibreRally.dll

Central vehicle dynamics coordinator.

Computes all vehicle forces each frame and applies them as impulses to BEPU bodies. BEPU remains responsible for rigid-body integration and collision; this system calculates tyre forces, load transfer, drivetrain torque, suspension reactions, and anti-roll bar effects externally.

Per-frame update order:

1. Compute longitudinal and lateral load transfer from force-derived chassis acceleration.
2. Compute anti-roll bar forces from suspension compression difference.
3. Apply chassis body roll torque from suspension compression difference.
4. Split engine torque through the drivetrain (center diff → axle diffs → wheels).
5. Evaluate tyre model for each wheel (slip ratio, slip angle → Fx, Fy, Mz).
6. Estimate next-step chassis acceleration from the summed tyre forces.
7. Apply all computed forces/impulses to BEPU bodies.

Designed for 50+ simultaneous vehicles: uses fixed-size arrays, no per-frame allocations, struct-based per-wheel state.

Key references:

• Pacejka, "Tire and Vehicle Dynamics", 3rd Ed.
• Milliken & Milliken, "Race Car Vehicle Dynamics".
• Abdulrahim, "Measurement and Analysis of Rally Car Dynamics at High Attitude Angles".

public sealed class VehicleDynamicsSystem

Inheritance

object

VehicleDynamicsSystem

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

VehicleDynamicsSystem()

Initializes a new dynamics system with default tyre state and tarmac surfaces.

public VehicleDynamicsSystem()

Fields

BepuAverageDamping

Per-wheel average damping coefficient (N·s/m) that BEPU's LinearAxisServo constraint uses. The correction impulse compensates for the difference between this and the direction-aware value.

public readonly float[] BepuAverageDamping

Field Value

float[]

BodyRoll

Chassis body roll system. Generates roll torque from left/right suspension compression difference and applies it as an angular impulse to the chassis.

public ChassisBodyRollSystem BodyRoll

Field Value

ChassisBodyRollSystem

BumpDamping

Per-wheel bump (compression) damping coefficient (N·s/m). Loaded from BeamNG damp_bump_* vars.

public readonly float[] BumpDamping

Field Value

float[]

BumpStopForces

Progressive bump-stop support force per wheel (N). Only active near maximum compression.

public readonly float[] BumpStopForces

Field Value

float[]

CurrentNormalLoads

Current normal load per wheel after load transfer (N). Read by telemetry.

public readonly float[] CurrentNormalLoads

Field Value

float[]

DamperForces

Directional damper support force per wheel (N). Positive values oppose bump, negative oppose rebound.

public readonly float[] DamperForces

Field Value

float[]

EffectivePeakFrictionCoefficients

Effective per-wheel peak friction coefficient after surface/load/temperature modifiers.

public readonly float[] EffectivePeakFrictionCoefficients

Field Value

float[]

FL

Front-left wheel index.

public const int FL = 0

Field Value

int

FR

Front-right wheel index.

public const int FR = 1

Field Value

int

LateralForces

Lateral force per wheel (N). Read by telemetry.

public readonly float[] LateralForces

Field Value

float[]

LongitudinalForces

Longitudinal force per wheel (N). Read by telemetry.

public readonly float[] LongitudinalForces

Field Value

float[]

OverturningCouples

Overturning couple per wheel (N·m) about the wheel forward axis.

public readonly float[] OverturningCouples

Field Value

float[]

RL

Rear-left wheel index.

public const int RL = 2

Field Value

int

RR

Rear-right wheel index.

public const int RR = 3

Field Value

int

ReboundDamping

Per-wheel rebound (extension) damping coefficient (N·s/m). Loaded from BeamNG damp_rebound_* vars.

public readonly float[] ReboundDamping

Field Value

float[]

RollingResistanceMoments

Rolling-resistance moment per wheel (N·m) about the wheel right axis.

public readonly float[] RollingResistanceMoments

Field Value

float[]

SelfAligningTorques

Self-aligning torque per wheel (N·m). Applied to steering system.

public readonly float[] SelfAligningTorques

Field Value

float[]

SpringForces

Hooke-law spring support force per wheel (N). Positive values increase tyre normal load.

public readonly float[] SpringForces

Field Value

float[]

SpringStiffness

Per-wheel spring stiffness (N/m), used when translating suspension compression into tyre load.

public readonly float[] SpringStiffness

Field Value

float[]

StaticNormalLoads

Static normal load per wheel (N), set during vehicle build.

public readonly float[] StaticNormalLoads

Field Value

float[]

SuspensionCompression

Signed suspension travel per wheel (m). Positive = compressed, negative = rebound.

public readonly float[] SuspensionCompression

Field Value

float[]

SuspensionMaximumCompression

Maximum bump/compression travel per wheel (m).

public readonly float[] SuspensionMaximumCompression

Field Value

float[]

SuspensionMaximumDroop

Maximum droop/rebound travel magnitude per wheel (m).

public readonly float[] SuspensionMaximumDroop

Field Value

float[]

SuspensionVelocity

Suspension compression velocity per wheel (m/s). Positive = compressing into bump.

public readonly float[] SuspensionVelocity

Field Value

float[]

TyreModels

Tyre model for each wheel (may share instances if identical).

public readonly TyreModel?[] TyreModels

Field Value

TyreModel[]

WheelBrakeTorques

Brake torque applied to each wheel this frame (N·m).

public readonly float[] WheelBrakeTorques

Field Value

float[]

WheelCount

Total number of wheels modeled by the system.

public const int WheelCount = 4

Field Value

int

WheelDriveTorques

Drive torque delivered to each wheel after differential (N·m).

public readonly float[] WheelDriveTorques

Field Value

float[]

WheelGrounded

Whether each wheel currently has ground contact.

public readonly bool[] WheelGrounded

Field Value

bool[]

WheelStates

Mutable per-wheel tyre state (temperature, wear, angular velocity, deflection).

public readonly TyreState[] WheelStates

Field Value

TyreState[]

WheelSurfaces

Surface properties currently under each wheel.

public readonly SurfaceProperties[] WheelSurfaces

Field Value

SurfaceProperties[]

WheelTyreReactionTorques

Tyre reaction torque opposing wheel rotation (N·m).

public readonly float[] WheelTyreReactionTorques

Field Value

float[]

Properties

AntiDiveFactor

Anti-dive geometry fraction in the range [0, 1]. Higher values reduce braking pitch/load transfer.

public float AntiDiveFactor { get; set; }

Property Value

float

AntiSquatFactor

Anti-squat geometry fraction in the range [0, 1]. Higher values reduce acceleration squat/load transfer.

public float AntiSquatFactor { get; set; }

Property Value

float

CenterDiff

Center differential configuration (AWD torque split front/rear).

public DifferentialConfig CenterDiff { get; set; }

Property Value

DifferentialConfig

CgHeight

Centre-of-gravity height above ground (m). Affects load transfer magnitude.

public float CgHeight { get; set; }

Property Value

float

DeliveredDrivetrainTorque

Total drivetrain torque delivered to the wheel shafts after differential limits (N·m).

public float DeliveredDrivetrainTorque { get; }

Property Value

float

DriveFrontAxle

Whether the front axle receives drive torque.

public bool DriveFrontAxle { get; set; }

Property Value

bool

DriveRearAxle

Whether the rear axle receives drive torque.

public bool DriveRearAxle { get; set; }

Property Value

bool

DrivetrainTorqueShortfall

Signed undelivered drivetrain torque caused by traction or differential limits (N·m), with the same sign as RequestedDrivetrainTorque.

public float DrivetrainTorqueShortfall { get; }

Property Value

float

FrontAntiRollStiffness

Front anti-roll bar stiffness (N/m of compression difference). 0 = disabled.

public float FrontAntiRollStiffness { get; set; }

Property Value

float

FrontAxleDeliveredTorque

Delivered front-axle drive torque after the center differential (N·m).

public float FrontAxleDeliveredTorque { get; }

Property Value

float

FrontDiff

Front axle differential configuration.

public DifferentialConfig FrontDiff { get; set; }

Property Value

DifferentialConfig

FrontRollCenterHeight

Front axle roll-center height above ground (m). Reduces the sprung-mass roll moment arm.

public float FrontRollCenterHeight { get; set; }

Property Value

float

RearAntiRollStiffness

Rear anti-roll bar stiffness (N/m of compression difference). 0 = disabled.

public float RearAntiRollStiffness { get; set; }

Property Value

float

RearAxleDeliveredTorque

Delivered rear-axle drive torque after the center differential (N·m).

public float RearAxleDeliveredTorque { get; }

Property Value

float

RearDiff

Rear axle differential configuration.

public DifferentialConfig RearDiff { get; set; }

Property Value

DifferentialConfig

RearRollCenterHeight

Rear axle roll-center height above ground (m). Reduces the sprung-mass roll moment arm.

public float RearRollCenterHeight { get; set; }

Property Value

float

RequestedDrivetrainTorque

Total drivetrain torque requested at the wheels before traction limiting (N·m).

public float RequestedDrivetrainTorque { get; }

Property Value

float

TrackWidth

Left-to-right wheel centre distance (m). Used for lateral load transfer.

public float TrackWidth { get; set; }

Property Value

float

VehicleMass

Total vehicle mass including chassis + wheels (kg).

public float VehicleMass { get; set; }

Property Value

float

Wheelbase

Front-to-rear axle distance (m).

public float Wheelbase { get; set; }

Property Value

float

Methods

GetTotalSelfAligningTorque()

Returns the total self-aligning torque from all wheels. This should be fed back to the steering system to provide force feedback.

public float GetTotalSelfAligningTorque()

Returns

float

The combined self-aligning torque generated by the steered wheels.

Update(BodyComponent, in Matrix, ReadOnlySpan<Vector3>, ReadOnlySpan<Vector3>, ReadOnlySpan<Vector3>, ReadOnlySpan<Vector3>, ReadOnlySpan<Matrix>, ReadOnlySpan<float>, ReadOnlySpan<bool>, ReadOnlySpan<float>, float, ReadOnlySpan<float>, ReadOnlySpan<float>, float)

Main per-frame update. Computes all vehicle dynamics and applies impulses to BEPU bodies.

Called from Update() after input processing and motor commands.

public void Update(BodyComponent chassisBody, in Matrix chassisWorld, ReadOnlySpan<Vector3> wheelContactPoints, ReadOnlySpan<Vector3> suspensionAttachmentPoints, ReadOnlySpan<Vector3> suspensionAxes, ReadOnlySpan<Vector3> wheelVelocities, ReadOnlySpan<Matrix> wheelOrientations, ReadOnlySpan<float> wheelContactScales, ReadOnlySpan<bool> wheelGrounded, ReadOnlySpan<float> suspensionCompressions, float engineTorqueAtWheels, ReadOnlySpan<float> brakeTorque, ReadOnlySpan<float> camberAngles, float dt)

Parameters

chassisBody BodyComponent

BEPU rigid body for the chassis.

chassisWorld Matrix

Chassis world transform matrix.

wheelContactPoints ReadOnlySpan<Vector3>

World-space tyre contact patch position for each wheel.

suspensionAttachmentPoints ReadOnlySpan<Vector3>

World-space chassis-side suspension attachment point for each wheel.

suspensionAxes ReadOnlySpan<Vector3>

World-space suspension axis for each wheel. Positive travel points toward bump/compression.

wheelVelocities ReadOnlySpan<Vector3>

World-space linear velocity at each wheel.

wheelOrientations ReadOnlySpan<Matrix>

World-space orientation frames for each wheel (Right, Up, Forward).

wheelContactScales ReadOnlySpan<float>

Per-wheel contact confidence/load scales in the range [0, 1].

wheelGrounded ReadOnlySpan<bool>

Whether each wheel has ground contact.

suspensionCompressions ReadOnlySpan<float>

Signed suspension travel for each wheel (m). Positive = compressed.

engineTorqueAtWheels float

Total engine torque after gearbox at wheel level (N·m).

brakeTorque ReadOnlySpan<float>

Brake torque per wheel (N·m).

camberAngles ReadOnlySpan<float>

Camber angle per wheel (rad).

dt float

Physics timestep (s).