Class WheelControllerGroup

Groups wheels belonging to the same Rigidbody for coordinated physics updates. Handles force accumulation and state integration during substepping.

Inheritance

object

WheelControllerGroup

Namespace: NWH.WheelController3D

Assembly: NWH.WheelController.dll

Syntax

public class WheelControllerGroup

Constructors

WheelControllerGroup(Rigidbody)

Creates a group bound to the given Rigidbody.

Declaration

public WheelControllerGroup(Rigidbody rb)

Parameters

Type	Name	Description
Rigidbody	rb

Fields

groupDriveActive

True when any grounded wheel's net drive torque (motor minus slope-hold) exceeds its brakes — same condition that makes CheckEarlyWakeConditions break static every substep. Fresh static entry is blocked while set: an undriven wheel that entered would be broken again next substep, pulsing force at the substep rate (low-speed creep shake).

Declaration

public bool groupDriveActive

Field Value

Type	Description
bool

groupHoldIntent

True when the rig is at rest AND a brake/handbrake is applied: the driver is commanding a hold, not a launch. Under StaticDriveBreakMode.DemandGated, drive does not break static then, so the vehicle holds still under handbrake+throttle on a slope. Cleared when the brake releases or the rig moves, so launches are unaffected. Set in CheckEarlyWakeConditions.

Declaration

public bool groupHoldIntent

Field Value

Type	Description
bool

isAsleep

True while the rigidbody sleeps and no wheel torque demands a wake. The manager skips the whole group so the EndFrame velocity write can't keep the body awake.

Declaration

public bool isAsleep

Field Value

Type	Description
bool

rigidBodyReadyForStaticEntry

True when rigidbody linear and angular velocity are low enough for all wheels to capture their static-friction anchor at a consistent pose. Avoids the 4-anchor-mismatch where wheels enter static across different substeps/poses, leaving residual multi-kN spring forces that cancel in the sum but net to a slow sideways drift. Set in BeginSubstep.

Declaration

public bool rigidBodyReadyForStaticEntry

Field Value

Type	Description
bool

rigidbody

Rigidbody shared by all wheels in this group.

Declaration

public Rigidbody rigidbody

Field Value

Type	Description
Rigidbody

state

Cached Rigidbody state integrated during substepping.

Declaration

public WheelControllerState state

Field Value

Type	Description
WheelControllerState

substepCallback

Optional callback invoked before each substep. Set by VehicleController to run powertrain.

Declaration

public ISubstepCallback substepCallback

Field Value

Type	Description
ISubstepCallback

substepForce

Net force accumulated from all wheels this substep, in world space (N).

Declaration

public Vector3 substepForce

Field Value

Type	Description
Vector3

substepTorque

Net torque accumulated from all wheels this substep, about the center of mass (Nm).

Declaration

public Vector3 substepTorque

Field Value

Type	Description
Vector3

targetEffectiveRateOverride

Override targetEffectiveRate for this group. Values of zero or less use global rate. Not set by any built-in system; available to game code for per-vehicle rates.

Declaration

public float targetEffectiveRateOverride

Field Value

Type	Description
float

wheels

Wheels belonging to this group.

Declaration

public List<WheelController> wheels

Field Value

Type	Description
List<WheelController>

wheelsSet

Membership set mirroring wheels for fast duplicate checks.

Declaration

public HashSet<WheelController> wheelsSet

Field Value

Type	Description
HashSet<WheelController>

Properties

WheelCount

Number of wheels in this group.

Declaration

public int WheelCount { get; }

Property Value

Type	Description
int

Methods

AccumulateFrictionForce(Vector3, Vector3)

Accumulate friction force from a wheel.

Declaration

public void AccumulateFrictionForce(Vector3 force, Vector3 contactPoint)

Parameters

Type	Name	Description
Vector3	force
Vector3	contactPoint

AccumulateSuspensionForce(Vector3, Vector3)

Accumulate suspension force from a wheel.

Declaration

public void AccumulateSuspensionForce(Vector3 force, Vector3 applicationPoint)

Parameters

Type	Name	Description
Vector3	force
Vector3	applicationPoint

ApplyHitBodyForces()

Apply forces to other rigidbodies that wheels contacted.

Declaration

public void ApplyHitBodyForces()

ApplyWheelTransforms()

Apply wheel transforms to Unity Transform components. Called once per frame after all substeps - deferred to reduce API calls.

Declaration

public void ApplyWheelTransforms()

BeginFrame()

Begin a new FixedUpdate cycle - read state from Rigidbody.

Declaration

public void BeginFrame()

BeginSubstep(float)

Begin a new substep - reset substep accumulators and wheel stepped flags.

Declaration

public void BeginSubstep(float substepDt)

Parameters

Type	Name	Description
float	substepDt

BreakAllStaticFriction(bool)

Force all grounded wheels to exit static friction mode.

Declaration

public void BreakAllStaticFriction(bool clearFilterHistory = true)

Parameters

Type	Name	Description
bool	clearFilterHistory

CalculateARB(float)

Axle coupling for all wheel pairs: anti-roll bar plus geometric roll-center load transfer. Called once per substep after all wheels have updated spring and friction data.

Declaration

public void CalculateARB(float substepDt)

Parameters

Type	Name	Description
float	substepDt

CheckEarlyWakeConditions()

Wakes all wheels if any wheel's motor torque would break static friction, so unpowered wheels (e.g. front wheels on RWD) wake together with the powered ones.

Declaration

public void CheckEarlyWakeConditions()

CoordinateStaticFrictionBreak()

Coordinate static friction break across all wheels in this group. When any grounded wheel breaks out of static friction, all other grounded wheels in static mode must also break.

Declaration

public bool CoordinateStaticFrictionBreak()

Returns

Type	Description
bool

Deregister(WheelController)

Remove a wheel from the group and rebuild ARB pairs.

Declaration

public void Deregister(WheelController wheel)

Parameters

Type	Name	Description
WheelController	wheel	Wheel to remove.

EndFrame()

End frame - apply velocity changes to actual Rigidbody.

Declaration

public void EndFrame()

EndSubstep(float)

End substep - apply accumulated forces to state and integrate.

Declaration

public void EndSubstep(float substepDt)

Parameters

Type	Name	Description
float	substepDt

EvaluateSleepSkip()

Decides whether this group is skipped this frame. Wakes a sleeping rigidbody when a wheel has pending motor torque so directly-driven wheels can move the vehicle again.

Declaration

public bool EvaluateSleepSkip()

Returns

Type	Description
bool

RebuildARBPairs()

Build anti-roll bar wheel pairs based on position. Pairs wheels with similar Z (fore-aft) and opposite X (left-right). Called during registration when wheel count changes.

Declaration

public void RebuildARBPairs()

Register(WheelController)

Add a wheel to the group and rebuild ARB pairs.

Declaration

public void Register(WheelController wheel)

Parameters

Type	Name	Description
WheelController	wheel	Wheel to add.

Events

OnStaticFrictionBroke

Fired when static friction breaks on any wheel and propagates to all wheels.

Declaration

public event Action OnStaticFrictionBroke

Event Type

Type	Description
Action

OnSubstepComplete

Fired after each substep completes (EndSubstep has applied accumulated forces and integrated state). Passes the substep dt. Lets subscribers see per-substep behaviour that end-of-FixedUpdate snapshots alias away (sub-frame limit cycles).

Declaration

public event Action<float> OnSubstepComplete

Event Type

Type	Description
Action<float>