Linked mounts
A truck and its trailer. A tank and its turret. A motorcycle and its sidecar. Two actors, two mountable components, one vehicle — and a set of questions that only make sense about the vehicle: who is driving it, who is aboard it, get everybody out of it.
Linking is how you say that. It is four lines of setup and it changes nothing about how a mount is found or mounted: the trailer's door is still the trailer's door, and a rider walking up to it still gets the trailer's seat. What it adds is the whole-vehicle view.
Coupling
// On the server. The child points at the parent.
UEDMountableComponent* TrailerMount = Trailer->FindComponentByClass<UEDMountableComponent>();
TrailerMount->LinkToMount(Truck);
// ...and later
TrailerMount->UnlinkFromMount();
LinkToMount returns false if the parent is not a mount, or if the link would make a cycle. The
cycle check is not paranoia: a loop would make GetLinkedRoot walk until its depth cap and quietly
give the wrong answer to every query below, which is the kind of bug that only appears the first time
somebody builds a road train.
LinkedParent is also editable in the details panel, for a vehicle whose parts are placed together in
the level and never come apart.
Asking about the vehicle
UEDMountableComponent* Root = TrailerMount->GetLinkedRoot(); // the truck; itself when unlinked
TArray<UEDMountableComponent*> Set;
TrailerMount->GetLinkedMountables(Set, /*bIncludeSelf*/ true); // root first, then the rest
bool bSameVehicle = TrailerMount->IsLinkedTo(Truck); // true from either end
APawn* Driver = TrailerMount->GetLinkedDriver(); // whoever is steering the whole thing
TArray<APawn*> Aboard;
TrailerMount->GetLinkedRiders(Aboard);
TrailerMount->EjectAllRidersInLinkedSet(); // authority only
The link is stored in one direction, child to parent, because a link stored at both ends is a link that can disagree with itself. The children are found by asking the subsystem which registered mounts share a root — the registry is the one list that is always current, so there is no second structure to keep in step and nothing to repair when an actor is destroyed.
OnLinkChanged fires on every machine when a mount is coupled or uncoupled, which is where a game
re-weighs the vehicle or redraws its HUD.
Getting in "the truck"
By default a request that names an actor puts you in that actor. Set bAllowLinkedMounts and it will
fall through to the rest of the set when the named mount has no seat for you:
FEDMountRequest Request;
Request.MountActor = Truck;
Request.bAllowLinkedMounts = true; // the truck, or its trailer, whichever has room
Rider->RequestMountWithOptions(Request);
The fallback is resolved once, in RequestMountWithOptions, and the resolved request is what gets
predicted locally and sent to the server. Resolving it separately on each machine would be two
answers to "which trailer has room", and a client would predict its way into a seat the server had
already given to somebody else.
The named mount is always tried first, and a failure still names the actor the caller asked about — so "the truck is full" does not become "the trailer is full" in your UI.
What a link is not
It is not attachment. Linking does not parent one actor to the other, move anything, or make the trailer follow the truck; do that with the engine's attachment or a physics constraint, whichever your vehicle needs. A link is a statement about ownership of riders, nothing else, which is why coupling and uncoupling are cheap and safe to do at runtime while people are aboard.
That separation is deliberate rather than an omission. A lift, a train carriage, a tow rope and a docked spacecraft are all linked mounts, and no two of them are held together the same way — a framework that picked one would be wrong for the other three.
Making the physics follow the link is a few lines, and it belongs to you. OnLinkChanged fires on
every machine, including one that joined after the coupling happened, so it is the only hook needed:
void UMyTowComponent::BeginPlay()
{
Super::BeginPlay();
if (UEDMountableComponent* Mountable = GetOwner()->FindComponentByClass<UEDMountableComponent>())
{
Mountable->OnLinkChanged.AddDynamic(this, &UMyTowComponent::HandleLinkChanged);
}
HandleLinkChanged(nullptr); // whatever the level already said
}
void UMyTowComponent::HandleLinkChanged(AActor*)
{
UEDMountableComponent* Mountable = GetOwner()->FindComponentByClass<UEDMountableComponent>();
if (AActor* Parent = Mountable->GetLinkedParent())
{
Hitch->SetConstrainedComponents(TrailerBody, NAME_None, TowBodyOf(Parent), NAME_None);
}
else
{
Hitch->BreakConstraint();
}
}
The example project's trailer is exactly that: UEDMountExampleTowComponent, forty lines, dropped on
an actor that has a physics constraint at its hitch. Set the link and the trailer is towed; clear it
and it rolls away. Only the authority may set the link, and only the authority should move the
trailer into position — every other machine is carried there by replicated movement.
Four things that went wrong writing that forty lines
None of them is a framework problem, and all four look like one from the outside, so they are written down here rather than in a commit message.
Opening a constraint is not SetConstrainedComponents(nullptr, ...). That call ignores both null
arguments and then re-initialises the joint from whatever it was already holding, so the trailer was
re-hitched by the same call that dropped it. The tow key looked completely dead while the link itself
was clearing correctly every time. Use TermComponentConstraint() and then clear OverrideComponent1,
OverrideComponent2, ComponentName1, ComponentName2, ConstraintActor1 and ConstraintActor2
yourself.
Do not teleport a simulating body to make a joint. A rigid joint takes its rest pose from wherever the two bodies are when it is made, so it is tempting to move the trailer into place first — and at a hundred km/h that put both vehicles eleven metres in the air. The physics has already been handed the frame's transforms, and a Chaos vehicle simulates its wheels against them, so the correction lands a frame late and the joint pulls it in with everything it has. Snap only while both bodies are near enough to standing still, which covers the two cases that matter: a level that starts coupled, and a driver who has reversed up to a trailer and stopped.
A joint made across a gap is a joint that pulls for ever. Because the rest pose is wherever the bodies were, coupling twenty-eight centimetres short does not correct itself — it leaves the tow bar hauling on the car for the rest of the level, which showed up as the back wheels lifting off the road and the throttle doing nothing. So "can I pick this up" is a question about being lined up, not about being near: the example refuses anything more than a couple of metres from the coupled position or more than thirty-five degrees out of line, and says so on screen.
Do not measure a vehicle with GetActorBounds. It is a world-axis box around everything attached,
so it grows when the car throws smoke and swells and shrinks as the car turns; the tow distance
wandered by a metre between the hitch made at the start of the level and the one refused half a lap
later. The skeletal mesh asset's own bounds are no better — on the engine's sports car they are one
centimetre, which parks the trailer inside the truck. Measure the physics asset:
Physics->CalcAABB(Mesh, FTransform::Identity) is the shape the world actually touches, it is in
local space, and it does not move.
It is also not a driving relationship. The trailer receives no driver input because it has no driver's
seat; if you give it one, it gets its own driver and GetLinkedDriver returns whichever it finds
first, root outwards. A vehicle with two drivers is a design decision, not something the framework
will make for you.
It is also not a driving relationship. The trailer receives no driver input because it has no driver's
seat; if you give it one, it gets its own driver and GetLinkedDriver returns whichever it finds
first, root outwards. A vehicle with two drivers is a design decision, not something the framework
will make for you.