Any further questions?
Join our discordOur documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.
This feature is supported as of BeamNG.tech and .drive version 0.6.0 to latest.
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.
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.
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)”.
These are special arguments which are passed as flags to beamState.lua and change the way the couplers work.
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"],
Commonly used tags for coupling different vehicles together:
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 immediately 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.
Commonly used tags for coupling different vehicles together:
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"]
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"}],
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"]}],
Was this article helpful?