Trailer Hitch Module

TrailerHitch module

Enables vehicles to tow trailers equipped with TrailerModule. Creates a physics joint connection between towing vehicle and trailer at specified attachment points.

Key Features

  • Automatic detection of nearby trailers using trigger colliders
  • Configurable joint strength with breakable connections
  • Input state and lighting synchronization between towing vehicle and trailer
  • Both ball-hitch (free rotation) and hinge-only (vertical axis) connections
  • Power reduction option when no trailer attached
  • Multi-trailer chain support with dollies/connectors

Setup

  • Attachment Point must be a child of the GameObject containing the TrailerHitchModule.
  • Position at the ball hitch or coupling point on the vehicle.
  • A SphereCollider trigger is created at the attachment point on initialization.
  • TrailerModule attachment points must be on the same physics layer for detection.

Properties

  • Attachment Point - Transform where the trailer connects. Must be child of this GameObject.
  • Attachment Trigger Radius - Size of the detection trigger sphere (default: 0.4m).
  • Attachment Layer - Physics layer for trailer detection.
  • Attach On Enable - Auto-attach trailers in range when module enables.
  • Detachable - Whether the trailer can be detached after attachment.
  • Disconnect Mode - Determines which trailer to disconnect in multi-trailer chains:
    • Closest - Disconnects the trailer directly attached to this hitch.
    • Furthest - Walks the chain and disconnects the last non-dolly trailer.
  • Break Force - Maximum force the joint can withstand before breaking (default: Infinity).
  • Use Hinge Joint - Lock rotation around vertical axis. For articulated buses where lateral rotation is unwanted.
  • No Trailer Power Coefficient - Engine power multiplier when no trailer attached (default: 1.0). Prevents wheel spin with binary controllers.

Multi-Trailer API

For multi-trailer configurations (road trains):

// Get all trailers in the chain (optionally exclude dollies)
List<TrailerModule> chain = hitchModule.GetTrailerChain(includeDollies: true);

// Get the last non-dolly trailer in the chain
TrailerModule lastTrailer = hitchModule.GetLastTrailerInChain();

// Get count of actual trailers (excludes dollies)
int trailerCount = hitchModule.GetTrailerCount();

// Detach the furthest non-dolly trailer
hitchModule.DetachFurthestTrailer();

// Attach/detach programmatically
hitchModule.AttachTrailer(trailerWrapper);
hitchModule.DetachTrailer(vehicleController);

A dolly is a trailer with a non-detachable hitch acting as a connector between trailers.

Events

  • onTrailerAttach - Triggered when a trailer is successfully attached.
  • onTrailerDetach - Triggered when a trailer is detached.

Notes

  • Joint break detection handles Unity's inconsistent OnJointBreak callback.
  • Static friction is propagated from towing vehicle to trailer for synchronized movement.
  • The module synchronizes input states and lighting from the towing vehicle to the attached trailer each frame.

See also: Trailer Module