Table of Contents

Namespace LibreRally.Vehicle.Physics

Classes

BreakablePartComponent

Monitors the weld constraint each frame and breaks it when the measured constraint force exceeds BreakStrength.

Once broken, the part's BodyComponent becomes a free rigid body that interacts normally with the physics world.

Attach this to the same entity as the WeldConstraintComponent and the part's BodyComponent.

DifferentialSolver

Stateless differential torque-split calculations.

Torque path: engine → clutch → gearbox → center diff → front/rear diff → wheels.

Each differential splits its input torque to two outputs based on wheel speed difference and the configured DifferentialType.

All methods are static and allocation-free for performance with 50+ vehicles.

Reference: Milliken & Milliken, "Race Car Vehicle Dynamics", Chapter 6.

TyreModel

Slip-based tyre physics model combining brush tyre theory with Pacejka-like force curves.

Slip ratio (longitudinal): κ = (ω·R − Vx) / max(|Vx|, ε) where ω = wheel angular velocity, R = tyre radius, Vx = longitudinal velocity.

Slip angle (lateral): α = atan(Vy / |Vx|) where Vy = lateral velocity at the contact patch.

Forces are computed using a simplified Pacejka "Magic Formula": F = D · sin(C · atan(B·x − E·(B·x − atan(B·x)))) with load-sensitive peak factor D = µ·Fz and appropriate stiffness B.

Key references:

  • Pacejka, "Tire and Vehicle Dynamics", 3rd Ed., Chapters 3–4.
  • Brush tyre model: Milliken & Milliken, "Race Car Vehicle Dynamics", §2.5.
  • Rally high-slip: Abdulrahim, "Measurement and Analysis of Rally Car Dynamics at High Attitude Angles", SAE 2007.

Designed for struct-based per-wheel state (TyreState) to avoid per-frame heap allocations when simulating 50+ vehicles.

VehicleBuilderResult

Result of Build(VehicleDefinition, IReadOnlyDictionary<string, float>?).

VehicleDynamicsSystem

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

Builds the Stride entity graph and BEPU physics bodies for an assembled vehicle definition, including the chassis body and four wheel bodies connected by suspension constraints.

WheelSettings

Holds wheel constraint references and metadata so RallyCarComponent can drive throttle, brake, steering, and suspension-travel measurement each frame. Also stores references to the tyre model and dynamics system.

Structs

ChassisBodyRollSystem

Computes chassis body attitude torque from suspension compression differences.

For each axle the compression delta between left and right wheels generates a roll moment about the vehicle's longitudinal axis: 

τ_roll = (compression_left − compression_right) × rollStiffness

The average front-versus-rear compression difference also generates a pitch moment about the vehicle's lateral axis:

τ_pitch = (avgFrontCompression − avgRearCompression) × pitchStiffness

The resulting torques are applied as angular impulses to the chassis body each physics step, producing visible body lean and dive/squat from the measured suspension state rather than from arbitrary visual offsets.

This is a reduced-order, torque-based body attitude model. It approximates the sprung-mass response from compression and acceleration terms and does not model full multi-body suspension kinematics (control-arm geometry, instant centers, etc.).

Design constraints:

  • Zero per-frame allocations — struct with no heap state.
  • Fixed-timestep safe — torque is converted to an impulse using the caller's dt.
  • Compatible with VehicleDynamicsSystem suspension compression arrays.

Reference: Milliken & Milliken, "Race Car Vehicle Dynamics", §17 — Roll stiffness and suspension geometry.

DifferentialConfig

Configuration for a single differential unit. Used for front, rear, or center differentials in an AWD drivetrain.

SurfaceProperties

Physics properties for a driving surface. These values scale the tyre model's grip envelope and energy dissipation.

Surface friction is decomposed into two texture-scale contributions following The Contact Patch, C1603:

  • FrictionCoefficient: overall peak µ multiplier relative to the tyre model's internal reference surface. Values near 1.0 are neutral; rally asphalt may be slightly above 1.0. This is the combined result of microtexture and macrotexture contributions.
  • Microtexture: adhesion-dominant grip from sub-0.5 mm asperity peaks (0–1 scale). Provides dry and light-wet grip. Polished surfaces have low microtexture. Reference: The Contact Patch, C1603, §Microtexture.
  • Macrotexture: hysteresis grip and water-evacuation capacity from 0.5–20 mm scale aggregate texture (0–1 scale). High macrotexture drains water from the contact patch, delaying hydroplaning onset. Reference: The Contact Patch, C1603, §Macro-texture.
  • WaterDepth: surface water film thickness (m). Zero for dry surfaces. Values above ~0.0025 m (2.5 mm) trigger hydroplaning risk at speed. Reference: The Contact Patch, C1603, §Aqua-planing.
  • RollingResistance: rolling-resistance force coefficient (N per N of load).
  • SlipStiffnessScale: scales the tyre's pure-slip stiffness and brush stiffness. Lower values make loose surfaces feel compliant rather than like low-grip asphalt.
  • RelaxationLengthScale: scales carcass relaxation lengths. Higher values delay force buildup on deformable or rough surfaces.
  • PeakSlipRatioScale: scales the longitudinal slip ratio at which peak traction occurs. Higher values allow more wheelspin before the tyre saturates.
  • DeformationFactor: how much the surface deforms under load (0 = rigid, 1 = fully deformable). Affects longitudinal slip behaviour — deformable surfaces tolerate higher slip before saturation.
  • NoiseFactor: road roughness amplitude (0 = smooth, 1 = very rough). Drives deterministic per-frame micro-variation in grip based on road-surface power spectral density, giving the feel of aggregate texture at the contact patch. Reference: The Contact Patch, C1603, §Power spectral density curves.
TyreState

Mutable per-wheel thermal and wear state. Updated every physics step by Update(ref TyreState, float, float, float, float, float, float, in SurfaceProperties, float, out float, out float, out float).

Temperature model reference: Salaani et al., "An Analytical Tire Model for Use in Vehicle Dynamics Simulations", SAE 2007-01-0816. Wear model: simplified abrasion proportional to slip energy dissipation.

Enums

DifferentialType

Differential type enumeration. Each type distributes engine torque differently between the two output shafts. Reference: Milliken & Milliken, "Race Car Vehicle Dynamics", §6.4.

SurfaceType

Identifies a driving surface material. Each type defines a unique set of friction, resistance, and deformation properties that modify tyre grip and slip behaviour.

Reference: Pacejka, "Tire and Vehicle Dynamics", Chapter 4 — road surface effects. Reference: The Contact Patch, C1603 — road surface texture and skid resistance.

TyreModelMode

Selects which tyre force model is active during physics simulation. Used by the physics calibration overlay to isolate and compare model contributions.