Class TrailerHitchModule

Module for towing vehicles that enables attachment of trailers.

Inheritance

object

VehicleComponent

TrailerHitchModule

Inherited Members

VehicleComponent.state

VehicleComponent.vehicleController

VehicleComponent.IsActive

VehicleComponent.VC_Initialize(VehicleController)

VehicleComponent.VC_SetDefaults()

VehicleComponent.VC_LoadStateFromStateSettings()

VehicleComponent.VC_DrawGizmos()

VehicleComponent.VC_Validate(VehicleController)

VehicleComponent.UpdateLOD()

VehicleComponent.ToggleState()

Namespace: NWH.VehiclePhysics2.Modules.Trailer

Assembly: NWH.VehiclePhysics2.dll

Syntax

[Serializable]
public class TrailerHitchModule : VehicleComponent

Remarks

The TrailerHitchModule allows a vehicle to tow trailers equipped with TrailerModule. It creates a physical joint connection between the towing vehicle and trailer at specified attachment points, enabling realistic trailer physics including articulation and weight transfer.

Key features: - Automatic detection of nearby trailers using trigger colliders - Configurable joint strength with breakable connections - Input state synchronization between towing vehicle and trailer - Support for both ball-hitch (free rotation) and fixed connections - Power reduction option when no trailer attached to prevent wheel spin

The module creates a SphereCollider trigger at the attachment point during initialization. When a TrailerModule's attachment point enters this trigger zone, pressing the attach/detach input (default 'T') will connect the trailer. The trailer is automatically positioned so both attachment points align.

For trailers instantiated after scene start, call SyncTrailers() manually to detect them.

Fields

attachOnEnable

Automatically attach trailers that are in range when the module is enabled.

Declaration

[FormerlySerializedAs("attachOnPlay")]
[Tooltip("If a trailer is in range when the scene is started it will be attached.")]
public bool attachOnEnable

Field Value

Type	Description
bool

Remarks

Useful for starting scenes with pre-attached trailers. If a trailer is within the trigger radius when the scene starts or the module enables, it will be automatically connected without requiring user input.

attached

Indicates whether a trailer is currently attached to this hitch.

Declaration

[Tooltip("True if object is trailer and is attached to a towing vehicle and also true if towing vehicle and has trailer\r\nattached.")]
public bool attached

Field Value

Type	Description
bool

Remarks

True when a trailer is successfully connected via the physics joint. Also true for trailers that have a towing vehicle attached. Updated automatically when trailers are attached or detached.

attachedTrailerModule

Reference to the currently attached trailer module.

Declaration

[NonSerialized]
[Tooltip("A trailer that is attached to this trailer hitch")]
public TrailerModule attachedTrailerModule

Field Value

Type	Description
TrailerModule

Remarks

Contains the TrailerModule component of the attached trailer, or null if no trailer attached. Use this to access the trailer's vehicle controller and modify its behavior.

attachmentLayer

Physics layer used for trailer detection.

Declaration

[Tooltip("The physics layer of the SphereCollider used to detect if the trailer module is in range.")]
public int attachmentLayer

Field Value

Type	Description
int

Remarks

The attachment trigger will only detect colliders on this layer. TrailerModule attachment points must be on the same layer for detection to work. Use a dedicated layer to avoid false detections with other objects.

attachmentPoint

Transform representing the hitch attachment point.

Declaration

[Tooltip("If the vehicle is a trailer, this is the object placed at the point at which it will connect to the towing vehicle. If the vehicle is towing, this is the object placed at point at which trailer will be coneected.")]
public Transform attachmentPoint

Field Value

Type	Description
Transform

Remarks

Position where the trailer will be connected. The trailer's attachment point will be moved to align with this position when attached. This is also where the physics joint is created.

Must be a child of the GameObject containing the TrailerHitchModule. Position this at the ball hitch or coupling point on the vehicle.

attachmentTriggerRadius

Radius of the trigger zone for detecting trailers.

Declaration

[Tooltip("The radius of the SphereCollider used to detect if the trailer module is in range.")]
public float attachmentTriggerRadius

Field Value

Type	Description
float

Remarks

Determines the size of the SphereCollider trigger created at the attachment point. Larger values make attachment easier but may detect trailers that aren't properly aligned.

Typical values: - 0.2-0.3: Precise alignment required - 0.4-0.5: Standard ease of use - 0.6-1.0: Very forgiving attachment

breakForce

Maximum force the joint can withstand before breaking.

Declaration

[Tooltip("Breaking force of the generated joint.")]
public float breakForce

Field Value

Type	Description
float

Remarks

When forces exceed this value, the joint breaks and the trailer detaches. Set to Mathf.Infinity for unbreakable connections.

Typical values: - 10000-50000: Light duty, easily broken - 50000-200000: Standard strength - 200000-500000: Heavy duty - Infinity: Unbreakable connection

detachable

Allows the trailer to be detached after attachment.

Declaration

[Tooltip("Can the trailer be detached once it is attached?")]
public bool detachable

Field Value

Type	Description
bool

Remarks

When false, trailers cannot be detached once connected. Useful for permanent connections or specialized vehicles. The connection can still break if breakForce is exceeded.

disconnectMode

Determines disconnect behavior for multi-trailer chains.

Declaration

[Tooltip("Closest: Disconnect trailer attached to this hitch. Furthest: Disconnect last trailer in chain.")]
public TrailerDisconnectMode disconnectMode

Field Value

Type	Description
TrailerDisconnectMode

noTrailerPowerCoefficient

Engine power multiplier when no trailer is attached.

Declaration

[Tooltip("Power reduction that will be applied when vehicle has no trailer to avoid wheel spin when controlled with a binary controller.")]
public float noTrailerPowerCoefficient

Field Value

Type	Description
float

Remarks

Reduces engine power when running without a trailer to prevent wheel spin with binary controllers. Helps maintain traction for vehicles designed to pull heavy loads.

Values: - 1.0: Full power without trailer - 0.7-0.9: Mild reduction - 0.5-0.7: Significant reduction for heavy trucks

onTrailerAttach

Event triggered when a trailer is successfully attached.

Declaration

public UnityEvent onTrailerAttach

Field Value

Type	Description
UnityEvent

Remarks

Subscribe to this event to update UI, play sounds, or trigger animations when a trailer connects.

onTrailerDetach

Event triggered when a trailer is detached.

Declaration

public UnityEvent onTrailerDetach

Field Value

Type	Description
UnityEvent

Remarks

Subscribe to this event to update UI, play sounds, or handle cleanup when a trailer disconnects.

trailerInRange

Indicates if a trailer's attachment point is within connection range.

Declaration

[Tooltip("Is trailer's attachment point close enough to be attached to the towing vehicle?")]
public bool trailerInRange

Field Value

Type	Description
bool

Remarks

True when a TrailerModule attachment point is inside the trigger zone. Used to display attachment prompts in UI. Only valid for one frame after detection.

useHingeJoint

Use a hinge joint instead of configurable joint for attachment.

Declaration

[Tooltip("Use for articulated buses and equipment where roll rotation should be prevented.")]
public bool useHingeJoint

Field Value

Type	Description
bool

Remarks

Creates a fixed connection that only allows rotation around the vertical axis. Useful for articulated buses, logging equipment, or specialized trailers where lateral rotation (roll) should be prevented.

When false, uses a ball joint allowing free rotation in all axes.

Methods

AttachTrailer(TrailerModuleWrapper)

Attaches a trailer to this hitch.

Declaration

public void AttachTrailer(TrailerModuleWrapper trailerWrapper)

Parameters

Type	Name	Description
TrailerModuleWrapper	trailerWrapper	The wrapper component of the trailer to attach

Remarks

Creates a physics joint between the vehicles at their attachment points. The trailer is repositioned so attachment points align, then a ConfigurableJoint is created with settings based on useHingeJoint flag.

Also synchronizes input states and lighting between vehicles and triggers the onTrailerAttach event.

DetachFurthestTrailer()

Detaches the furthest non-connector trailer in the chain.

Declaration

public void DetachFurthestTrailer()

DetachTrailer(VehicleController)

Detaches the currently attached trailer.

Declaration

public void DetachTrailer(VehicleController vc)

Parameters

Type	Name	Description
VehicleController	vc	The vehicle controller of the towing vehicle

Remarks

Removes the physics joint connecting the trailer and triggers cleanup on both the hitch and trailer modules. Only works if detachable is true.

Triggers the onTrailerDetach event after successful detachment.

GetLastTrailerInChain()

Gets the last non-connector trailer in the chain (excludes trailers with non-detachable hitches).

Declaration

public TrailerModule GetLastTrailerInChain()

Returns

Type	Description
TrailerModule

GetTrailerChain(bool)

Gets all trailers in the chain, optionally excluding dollies.

Declaration

public List<TrailerModule> GetTrailerChain(bool includeDollies = true)

Parameters

Type	Name	Description
bool	includeDollies	If false, trailers with non-detachable hitches (connectors) are excluded

Returns

Type	Description
List<TrailerModule>	List of TrailerModules in order from nearest to furthest

GetTrailerCount()

Gets count of actual trailers (excludes connectors with non-detachable hitches).

Declaration

public int GetTrailerCount()

Returns

Type	Description
int

NoTrailerPowerModifier(float)

Power modifier function that reduces power when no trailer is attached.

Declaration

public float NoTrailerPowerModifier(float DeltaTime)

Parameters

Type	Name	Description
float	DeltaTime	Physics time step in seconds

Returns

Type	Description
float	Power coefficient to apply to engine output

Remarks

Registered with the engine's power modifiers to prevent wheel spin when operating without a trailer.

OnTriggerEnter(Collider)

Called when a collider enters the attachment trigger zone.

Declaration

public virtual void OnTriggerEnter(Collider other)

Parameters

Type	Name	Description
Collider	other	The collider that entered the trigger

Remarks

Detects TrailerModule attachment points entering the trigger zone. If attachOnEnable is true and this is the first frame, automatically triggers attachment.

OnTriggerExit(Collider)

Called when a collider exits the attachment trigger zone.

Declaration

public virtual void OnTriggerExit(Collider other)

Parameters

Type	Name	Description
Collider	other	The collider that exited the trigger

OnTriggerStay(Collider)

Called while a collider remains in the attachment trigger zone.

Declaration

public virtual void OnTriggerStay(Collider other)

Parameters

Type	Name	Description
Collider	other	The collider within the trigger

Remarks

Maintains awareness of trailers in range for attachment. Sets trailerInRange flag for UI feedback.

VC_Disable(bool)

Disables the component and stops updates. Override to add component-specific disable logic.

Declaration

public override bool VC_Disable(bool calledByParent)

Parameters

Type	Name	Description
bool	calledByParent	True if called by parent component or LOD system

Returns

Type	Description
bool	True if successfully disabled, false otherwise

Overrides

VehicleComponent.VC_Disable(bool)

Remarks

Component must be initialized before it can be disabled. Tracks whether disable was called by parent to manage LOD system interaction.

VC_Enable(bool)

Enables the component and starts updates. Override to add component-specific enable logic.

Declaration

public override bool VC_Enable(bool calledByParent)

Parameters

Type	Name	Description
bool	calledByParent	True if called by parent component or LOD system

Returns

Type	Description
bool	True if successfully enabled, false otherwise

Overrides

VehicleComponent.VC_Enable(bool)

Remarks

Will initialize the component if not already initialized. Components disabled by LOD system will track the parent caller to prevent manual enabling while LOD is controlling state.

VC_FixedUpdate(float)

Physics update called at fixed intervals. Override to implement physics-based behavior.

Declaration

public override void VC_FixedUpdate(float DeltaTime)

Parameters

Type	Name	Description
float	DeltaTime	Time elapsed since last FixedUpdate in seconds

Overrides

VehicleComponent.VC_FixedUpdate(float)

Remarks

Only called when the component is active (initialized and enabled). Use for physics calculations, force application, and other fixed-timestep operations. Called from VehicleController.FixedUpdate().

VC_Initialize()

Initializes the component's internal systems and resources. Called once during vehicle startup after the VehicleController reference is set.

Declaration

protected override void VC_Initialize()

Overrides

VehicleComponent.VC_Initialize()

Remarks

Override this to set up component-specific resources, cache references, or perform one-time initialization. Sets state.initialized to true on completion.

VC_Update(float)

Frame-rate dependent update called every frame. Override for visual updates and input handling.

Declaration

public override void VC_Update(float DeltaTime)

Parameters

Type	Name	Description
float	DeltaTime	Time elapsed since last Update in seconds

Overrides

VehicleComponent.VC_Update(float)

Remarks

Only called when the component is active (initialized and enabled). Use for visual effects, UI updates, and other frame-dependent operations. Avoid physics calculations here - use VC_FixedUpdate instead.