The coupler system is the feature of connecting two nodes together. Connected nodes will be within a closed position range from each other and will react to the same forces. Before connecting, the nodes will move towards each other when the distance between them reaches a specified range. It can work between nodes of the same vehicle or 2 different vehicles, either automatically or on key press. Some use cases of the system include rigid attachments between vehicle parts, tow hitches for trailers, and latches for vehicle doors, hoods, trunks and tailgates.
For this system to work, you need a node with a couplerTag property, and another node with a Tag property of the same value. For the purpose of this section, we shall call them the “coupler node” and “tag node” respectively, to understand easier which properties are meant for which node. When connecting a vehicle to a trailer, the end of the tow hitch on the vehicle should be the coupler node while the end of the tow hitch receiver on the trailer should be the tag node. When attaching 2 different parts of the same vehicle, the order doesn’t matter.
Functionality
The system will start working when the coupler node ends up in the Active state. Active coupler nodes and their respective tag nodes will be moved towards each other before being merged into one, the force will be the same in both directions. A connected coupler node is no longer referred to as Active. Broken coupler nodes cannot be switched to the Active state in any way and they will not connect to any tag nodes again.
When connecting 2 nodes from the same vehicle on spawn, it is best if they have identical coordinates by default. One coupler node can only connect to one tag node at a time, but it can be disconnected and then connected to the same or different tag node. Similarly, a tag node can be connected to one coupler node at a time, but after disconnecting it can be connected to the same or different coupler node.
The coupler system can also be controlled by the Advanced Coupler Control, which is too advanced for this section of documentation so it will not be covered here. Another system that can control couplers is Couplings, used on semi truck fifth wheel and trailers.
For the system itself, there is no difference (other than slight performance differences which should not concern you) whether the nodes are parts of the same vehicle or different vehicles. There are however various sub-systems that will only work when the system is set up between 2 different vehicles, such as the camera zoom out when connecting a vehicle to a trailer.
Coupler Toggle System
A system very closely related to this one, which allows to actually connect a trailer to a vehicle, is the Coupler Toggle System. It can be activated either by pressing a key binding assigned to it (L by default) or via the radial menu. Upon use, the system first checks if any of the nodes relevant for it are connected to other nodes. If there are any, it disconnects them, and if not, it sets the ones that are not in the Broken state to Active state and toggles a visualization of coupler nodes and tag nodes via color coded balls, the same tags and couplerTags will have the same colors.
A node is relevant for the Coupler Toggle System if it has a couplerTag property, its state is not Broken, and it does not have the couplerLock or couplerWeld property. This means that only the nodes referred to as coupler nodes in this section can be relevant for this system.
You can activate the Coupler Toggle System with a trigger . If you wish to activate it for all relevant couplers, use “beamstate.toggleCouplers()” without arguments as the function. However you can also provide arguments to it for specific functionality, for example:
"beamstate.toggleCouplers('pintle', true, false, true)",
The arguments used by the function are as follows:
Analogically you can use “beamstate.attachCouplers(_nodetag)” and “beamstate.detachCouplers(_nodetag, forceLocked, forceWelded)”.
Nodes section arguments
Common
Only relevant when connecting 2 different vehicles together. Mostly used when defining the tow hitch coupler on trailers. These are usually defined for the trailer, not for the towing vehicle. They can still be used on the towing vehicle, but keep in mind they will overwrite its own electrics.
"importElectrics": ["lowhighbeam", "reverse", "signal_L", "signal_R"],
Coupler node
Commonly used tags for coupling different vehicles together:
- “tow_hitch” - for standard car tow hitches and trailers
- “gooseneck_hitch” - for pickup truck gooseneck hitches and trailers
- “fifthwheel_v2” - for semi-truck trailers (legacy tag for old mods: “fifthwheel”)
- “pintle” - for pintle hitch and trailer converter dolly
- Tags used for shipping container coupling: “cp1_h” - bottom horizontal, “cp2_h” - top horizontal, “cp_v” - vertical
You should avoid using these tags for coupling parts of the same vehicle.
This means that the nodes that are within this range with each other will try to connect immidiately after the vehicle is spawned, without the need to toggle them. When this property is not used, Active will not be the default state, meaning that the nodes will need to be toggled in order to connect.
This is most often used to connect parts of the same vehicle rather than trailers. It’s best if this value is very small, as is the distance between the parts on spawn which should ideally be 0, so that there is not much shifting right after spawn.
This means that a node that is not active on spawn can only become active via lua code which is not related to the Coupler Toggle System. Similarly, a node that is active on spawn (uses the couplerStartRadius property) can only disconnect when its state changes to Broken or when lua code is used.
This is useful for systems where a coupler needs to lock and unlock on demand, but should not be linked to the Coupler Toggle System and the use of advanced coupler control would be redundant. A good example is the lockable dump truck tailgate.
This means that a node that is not active on spawn can never become active, and a node that is active on spawn (uses the couplerStartRadius property) can only disconnect when its state changes to Broken.
This is often used when connecting together parts of lightweight rigid structures on the same vehicle, such as fiberglass body panels. With this property, couplerStartRadius should always be used, or else the nodes will never connect and couplerTag will do nothing.
Tag node
Commonly used tags for coupling different vehicles together:
- “tow_hitch” - for standard car tow hitches and trailers
- “gooseneck_hitch” - for pickup truck gooseneck hitches and trailers
- “fifthwheel_v2” - for semi-truck trailers (legacy tag for old mods: “fifthwheel”)
- “pintle” - for pintle hitch and trailer converter dolly
- Tags used for shipping container coupling: “cp1_h” - bottom horizontal, “cp2_h” - top horizontal, “cp_v” - vertical
You should avoid using these tags for coupling parts of the same vehicle.
Only relevant when connecting 2 different vehicles together. Mostly used when defining the tow hitch coupler on trailers. These should be defined for the trailer, not for the towing vehicle.
"importInputs": ["brake", "parkingbrake"]
Simple Example
Connecting together 2 nodes of the same vehicle.
Coupler node:
["hd4l4", 1.15, -1.26, 1.20, {"couplerTag":"hood_side_latch_L","breakGroup":"hood_side_latch_L","couplerStrength":12000,"couplerRadius":0.01,"couplerStartRadius":0.01,"couplerWeld":true}],
Tag node:
["sd1l", 0.85, -1.12, 1.41, {"tag":"hood_side_latch_L","breakGroup":"hood_side_latch_L"}],
Advanced Example
Connecting 2 vehicles together via tow hitch.
Vehicle tow hitch (coupler node):
["tw", 0.0, 2.76, 0.58,{"couplerTag":"tow_hitch","couplerStrength":2001000,"couplerRadius":1}],
Trailer tow ball end (tag node):
["cf8", 0.0, 0.245, 0.45, {"tag":"tow_hitch","couplerStrength":801000,"importElectrics": ["lowhighbeam", "reverse", "signal_L", "signal_R"],"importInputs": ["brake", "parkingbrake"]}],
