Class GroundDetectionBase

Abstract base class for wheel ground detection implementations in WheelController3D. Responsible for performing collision detection between wheels and ground surfaces.

Inheritance
object
Object
Component
Behaviour
MonoBehaviour
GroundDetectionBase
StandardGroundDetection
Namespace: NWH.WheelController3D
Assembly: NWH.WheelController.dll
Syntax
[RequireComponent(typeof(WheelController))]
public abstract class GroundDetectionBase : MonoBehaviour
Remarks

The default StandardGroundDetection provides 3D detection across the wheel's width and circumference using multiple sphere or ray casts. This is superior to single-point detection as it allows wheels to properly interact with curbs, rocks, and terrain irregularities.

Custom implementations might be needed for:

  • Special collision scenarios (e.g., voxel terrain, heightmap-based ground)
  • Performance optimization for specific game types
  • Specialized surface detection (water detection, destructible terrain, etc.)

Implementation requirements:

  • Must accurately consider both wheel radius and width
  • Should find the nearest hit point within the cast distance
  • Must filter out the vehicle's own colliders
  • Should populate all WheelHit fields when ground is detected

Methods

| Edit this page View Source

WheelCast(in Vector3, in Vector3, in float, in float, in float, ref WheelHit, LayerMask)

Performs a collision cast to detect ground contact beneath the wheel. Called every physics frame to update wheel ground contact state.

Declaration
public abstract bool WheelCast(in Vector3 origin, in Vector3 direction, in float distance, in float wheelRadius, in float wheelWidth, ref WheelHit result, LayerMask layerMask)
Parameters
Type Name Description
Vector3 origin

Cast starting point in world space (typically wheel suspension origin)
Vector3 direction

Cast direction in world space (typically vehicle's down vector)
float distance

Maximum cast distance in meters (typically suspension max length + wheel radius)
float wheelRadius

Wheel radius in meters, defines the wheel's circular boundary
float wheelWidth

Wheel width in meters, defines the lateral extent of the tire
WheelHit result

WheelHit structure to populate with contact data if ground is detected
LayerMask layerMask

Physics layer mask determining which layers can be detected
Returns
Type Description
bool

True if ground was detected within the cast distance, false if wheel is airborne
Remarks

When returning true, implementation must populate result with:

  • point: World-space contact point
  • normal: Surface normal at contact point (unit vector)
  • collider: The Collider component that was hit
  • localPoint/localNormal: Optional; providing these avoids matrix transformations in the caller

Important considerations:

  • Only detect the bottom hemisphere of the wheel (top collisions handled separately)
  • Exclude vehicle's own colliders to prevent self-collision
  • Return the closest hit if multiple surfaces are detected
  • Consider wheel width - hits outside the tire width should be ignored