Align For Coupling

Overview

Node Name: Align for Coupling
Behaviour: duration, once
File: extensions/flowgraph/nodes/vehicle/alignForCoupling.lua

Moves a trailer behind a pulling vehicle so their coupler points align, then optionally enables auto-coupling. Outputs flow once successfully coupled.

Pin Schema

Input Pins

Pin	Type	Default	Description
`flow`	flow	-	Inflow for this node.
`reset`	flow (impulse)	-	Resets the node.
`vehId`	number	-	ID of the pulling vehicle.
`trailerId`	number	-	ID of the trailer vehicle.
`rot`	number/quat	0	Rotation for the trailer. Number = degrees relative to puller. Quat = absolute/relative rotation (hidden).
`relativeRotationQuat`	bool	-	If true, quat rotation is relative to the pulling vehicle (hidden).
`ignoreCouple`	bool	true	If checked, skips automatic coupling activation (hidden).

Output Pins

Pin	Type	Description
`flow`	flow	Fires once vehicles are successfully coupled (or immediately if `ignoreCouple`).

Internals

Key Methods

Method	Description
`_executionStarted()`	Resets `done`, `waitForCouple`, and `coupled` flags.
`work()`	Computes coupler alignment matrix, teleports trailer, enables coupling, waits for couple confirmation.

State Flags

Flag	Description
`done`	Alignment calculation completed.
`waitForCouple`	Waiting for physical coupling to occur.
`coupled`	Coupling confirmed.

How It Works

Retrieves coupler offset positions for both vehicles from self.mgr.modules.vehicle.
Builds transformation matrices:
- v1CouplerMatrix - world-space position of the puller's coupler point.
- v2CouplerMatrix - local coupler offset of the trailer.
Computes a rotation matrix from the rot pin (degrees or quaternion).
Calculates the final trailer transform: v1CouplerMatrix * (rotMatrix * v2CouplerMatrix:inverse() * v2RefMatrix).
Teleports the trailer via v2:setTransform(res) and resets its physics.
Activates auto-coupling on the puller via beamstate.activateAutoCoupling().
Polls mgr.modules.vehicle:isCoupledTo() each frame until coupling is confirmed.

-- The core alignment math:
local result = v1CouplerMatrix * (rotMatrix * v2CouplerMatrix:inverse() * v2:getRefNodeMatrix())
v2:setTransform(result)
v2:queueLuaCommand('obj:requestReset(RESET_PHYSICS)')
v1:queueLuaCommand('beamstate.activateAutoCoupling()')

Usage Example

-- Flowgraph:
-- [Spawn Truck] → vehId ──→ [Align for Coupling] → flow → [Drive Away]
-- [Spawn Trailer] → trailerId ↗
--
-- Optionally rotate trailer 180° relative to truck:
-- rot = 180 (degrees)

Key Dependencies

mgr.modules.vehicle:getVehicle(id).couplerOffset - coupler offset data
mgr.modules.vehicle:isCoupledTo() - coupling status check
beamstate.activateAutoCoupling() - vehicle-side coupling activation
MatrixF - 4×4 transformation matrix operations

Overview

Node Name: Align for Coupling
Behaviour: duration, once
File: extensions/flowgraph/nodes/vehicle/alignForCoupling.lua

Moves a trailer behind a pulling vehicle so their coupler points align, then optionally enables auto-coupling. Outputs flow once successfully coupled.

Pin Schema

Input Pins

Pin	Type	Default	Description
`flow`	flow	-	Inflow for this node.
`reset`	flow (impulse)	-	Resets the node.
`vehId`	number	-	ID of the pulling vehicle.
`trailerId`	number	-	ID of the trailer vehicle.
`rot`	number/quat	0	Rotation for the trailer. Number = degrees relative to puller. Quat = absolute/relative rotation (hidden).
`relativeRotationQuat`	bool	-	If true, quat rotation is relative to the pulling vehicle (hidden).
`ignoreCouple`	bool	true	If checked, skips automatic coupling activation (hidden).

Output Pins

Pin	Type	Description
`flow`	flow	Fires once vehicles are successfully coupled (or immediately if `ignoreCouple`).

Internals

Key Methods

Method	Description
`_executionStarted()`	Resets `done`, `waitForCouple`, and `coupled` flags.
`work()`	Computes coupler alignment matrix, teleports trailer, enables coupling, waits for couple confirmation.

State Flags

Flag	Description
`done`	Alignment calculation completed.
`waitForCouple`	Waiting for physical coupling to occur.
`coupled`	Coupling confirmed.

How It Works

Retrieves coupler offset positions for both vehicles from self.mgr.modules.vehicle.
Builds transformation matrices:
- v1CouplerMatrix - world-space position of the puller's coupler point.
- v2CouplerMatrix - local coupler offset of the trailer.
Computes a rotation matrix from the rot pin (degrees or quaternion).
Calculates the final trailer transform: v1CouplerMatrix * (rotMatrix * v2CouplerMatrix:inverse() * v2RefMatrix).
Teleports the trailer via v2:setTransform(res) and resets its physics.
Activates auto-coupling on the puller via beamstate.activateAutoCoupling().
Polls mgr.modules.vehicle:isCoupledTo() each frame until coupling is confirmed.

-- The core alignment math:
local result = v1CouplerMatrix * (rotMatrix * v2CouplerMatrix:inverse() * v2:getRefNodeMatrix())
v2:setTransform(result)
v2:queueLuaCommand('obj:requestReset(RESET_PHYSICS)')
v1:queueLuaCommand('beamstate.activateAutoCoupling()')

Usage Example

-- Flowgraph:
-- [Spawn Truck] → vehId ──→ [Align for Coupling] → flow → [Drive Away]
-- [Spawn Trailer] → trailerId ↗
--
-- Optionally rotate trailer 180° relative to truck:
-- rot = 180 (degrees)

Key Dependencies

mgr.modules.vehicle:getVehicle(id).couplerOffset - coupler offset data
mgr.modules.vehicle:isCoupledTo() - coupling status check
beamstate.activateAutoCoupling() - vehicle-side coupling activation
MatrixF - 4×4 transformation matrix operations

Align For Coupling

Overview

Pin Schema

Input Pins

Output Pins

Internals

Key Methods

State Flags

How It Works

Usage Example

Key Dependencies

See Also

On this page

Align For Coupling

Overview

Pin Schema

Input Pins

Output Pins

Internals

Key Methods

State Flags

How It Works

Usage Example

Key Dependencies

See Also

On this page