Multiplayer
Although not all mods need special code to handle multiplayer, it’s important to create your mods with multiplayer in mind.
Adding support for multiplayer to your mod is similar to creating multiplayer code for any other Unreal Engine project.
Does your mod need special changes to support multiplayer?
Short answer: Try it yourself and find out!
Long answer: It’s complicated. It’s always best to test your mod to determine if it’s working or not. But, in general, if your mod only adds new items, recipes, and schematics, or adds content only by extending base-game classes, you probably don’t need to write any multiplayer code. As soon as you start handling user input or using custom logic to modify the state of the game, you should start thinking about multiplayer.
Before You Continue
Replication in Unreal Engine can be a very confusing system at first, so it’s important to build a strong understanding before continuing.
This Alex Forsythe video provides an excellent introduction to replication in Unreal Engine, and you should watch it before continuing on this page. By watching this video now, you’ll save yourself hours of troubleshooting in the future.
The rest of this page will assume you have watched, and understand, the video.
After watching the video, check out the Unreal Community Wiki’s replication page. You will not need to use every concept here, but understanding the factors at play will help you figure out what is going wrong when things don’t work as expected.
Consider checking out Unreal’s own examples in the Networking Content Examples pack.
Again, please watch the video before continuing. |
ExampleMod
The ExampleMod (included in the starter project) contains some examples of correctly adding multiplayer functionality to mods.
The examples are not exhaustive, but they should help you get started.
Remote Call Objects
Remote Call Objects are an Unreal concept described in the video. Note that dedicated servers have no player controller they can’t make use of Remote Call Objects. In that case, consider using a Replicated Subsystem instead.
Coffee Stain Studios has written custom code to make it easier for mods to register their own Remote Call Objects. The inner details of this system are described in the appendix.
Remote call objects can be registered via listing their classes in your Game Instance Module’s Remote Call Objects
array.
Remote call objects can be retrieved from a player controller instance via
FGPlayerController::GetRemoteCallObjectOfClass
which is accessible in both blueprints and C++.
If for some reason you need to manually register a remote call object it can be done via
FGPlayerController::RegisterRemoteCallObjectOfClass
or
FGGameMode::RegisterRemoteCallObjectClass
.
Do Not Use Multicast in RCOs!
It is important to note that since the RCOs are owned by the player controller, they do not exist on every connection. As such, you should not use them for any multicast RPCs - triggering one will softlock and crash client players! If you want to use Multicast, do it from an Replicated Subsystem instead.
An example why you should not do this is demonstrated in the ExampleMod.
Blueprint Example
Your remote call objects should inherit from BP Remote Call Object
.
The ExampleMod demonstrates blueprint remote call object registration and usage from a building.
C++ Example
Your remote call objects should inherit from FGRemoteCallObject
.
If you were to try this as is, it still won’t work because Unreal is weird and we still need to do one more thing.
You will need to add any kind of UPROPERTY
to the RCO, which is replicated.
That also means you need to add it to the GetLifetimeReplicatedProps
function.
This property just needs to exist, you don’t need to do anything with it.
Here is a small example C++ showing a simple RCO with one RPC.
UCLASS()
class DOCMOD_API UDocModRCO : public UFGRemoteCallObject {
GENERATED_BODY()
public:
UFUNCTION(Server, WithValidation, Reliable)
void SetSomeStuffOfTheDocMachineRPC(ADocMachine* machineContext, bool bSomeData);
UPROPERTY(Replicated)
bool bDummy = true;
};
The parameters of the RPC are just examples, but most of the time you actually want to pass one context parameter so you can change the state of the given context. With this example function we might allow the GUI to be able to reset the counter of the machine passed. Without the context it won’t be able to know of which machine it should reset the counter of.
The implementation of the RPC is not covered in this tutorial because that’s completely up to you to decide,
but below is a short example for the GetLifetimeReplicatedProps
function.
#include "Net/UnrealNetwork.h"
void UDocModRCO::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const {
Super::GetLifetimeReplicatedProps(OutLifetimeProps);
DOREPLIFETIME(UDocModRCO, bDummy);
}
Now in the GUI or wherever you need to call the RPC, you can just get the first player controller of the world
and then call the AFGPlayerController::GetRemoteCallObjectByClass
function and pass the class of your RCO to get the instance of the RCO for the client.
Here is a example calling the RPC in C++:
ADocMachine* machine = GetMachine(); // get the context object from somewhere
UWorld* world = machine->GetWorld(); // get the world context from anywhere, like a world
UDocModRCO* rco = Cast<AFGPlayerController>(world->GetFirstPlayerController())->GetRemoteCallObjectByClass(UDocModRCO::StaticClass()); // get the RCO instance from the player controller
rco->SetSomeStuffOfTheDocMachineRPC(machine, false); // call the RPC of the RCO
You might also want check if AFGPlayerController::GetRemoteCallObjectByClass
actually returns something.
It returns nothing (nullptr) under various conditions, such as when the RCO is not registered yet.
Replicated Mod Subsystems
Mod Subsystems are a concept implemented by Satisfactory Mod Loader.
Learn more about them on the Subsystems page.
Configure if a subsystem is replicated via its Replication Policy
field.
Replicated subsystems are a good place to implement multicast RPCs since they will be present on all connections.
C++ Example
No example is currently provided. Consider looking at an open-source mod instead.
Replicated Properties
Replication Detail Components
Replication Detail Components were previously critical in handling replication of inventories to multiplayer clients.
As of Update 8, this system has been replaced with a new system involving structs, which Arch has informed us is planned to be phased out soon. If you have questions about this system, please ask about it on the discord, as it’s not worth documenting something that will be removed so soon.
Appendix
Additional information on various topics.
Note on Client-to-Server Remote Procedure Calling
You might have noticed that triggering a Remote Procedure Call (RPC) isn’t as straightforward as it may first appear. The reason is simple: as you might be aware, to be able to call a RPC from the client, the calling object needs to be the authority of the object. This is only the case if the object is somehow owned by the player connection. The player controller, for example, is owned by the player connection.
As modders, we are not able to directly add more functionality to the player controller, so we are not able to add functions in the player connection owning scope at compile time.
Thankfully Coffee Stain has implemented a system that allows us to add functionality owned by the player connection afterwards in runtime.
This system is implemented through Remote Call Objects
.
Remote Call Objects (aka. RCOs) get created by the in runtime individually once for each player controller. CSS’s code handles the creation, replication, and ownership transfer to their respective player controllers for us.
The client owning the player controller is able to get the RCO instance by passing the class of the RCO to the AFGPlayerController::GetRemoteCallObjectByClass
function.
With that RCO reference, you will be able to call anywhere RPCs of the RCO, even in the GUI which exists only on the client side.