Game Server Hosting SDK for Unreal Engine
Note: The content on this page pertains to all versions of Multiplay, including Game Server Hosting (Multiplay) and Managed Game Server Hosting (Clanforge).
The Multiplay Game Server SDK for Unreal Engine includes all the functionality necessary to leverage Multiplay scaling and game server services in your game.
> Note: See Game Server Hosting SDK for Unity if you’re using the Unity Engine to develop your game.
Get started
The following instructions teach you how to install and configure the Multiplay Game Server SDK plug-in. After you’ve installed and configured the Multiplay Game Server SDK for your project, you can use the C++ or Blueprints integration.
Understand the requirements
The Multiplay Game Server SDK plug-in for Unreal Engine requires one of the following Unreal Engine versions:
- 4.22
- 4.23
- 4.24
- 4.25
- 4.26
- 4.27
- 5.0
Build the Engine from Source
Unreal Engine requires you to use a source build to set up a dedicated server. See Unreal Engine documentation on Setting Up Dedicated Servers.
Perform the following steps to build the Unreal Engine from source:
- Create an Epic Games account.
- Create a GitHub account.
- Link your Epic Games account to GitHub account.
- Clone the Unreal Engine source code using Git.
- Check out a branch corresponding to one of the engine versions specified above (for example, 4.27).
- Follow the Getting up and running instructions in the
README.md
file for the version of the engine that you have checked out.
At this point, you should have an Unreal Engine binary that you can use to create a project and install the plug-in.
Install the Multiplay Game Server SDK plug-in
You must install the Multiplay Game Server SDK before implementing the SDK using C++ or Blueprints.
To install the plug-in in Unreal Engine:
Download the Multiplay Game Server SDK plug-in.
- From the Unity Dashboard, select Multiplayer on the left.
- Select Multiplayer > Game Server Hosting > Packages & SDKs.
- Select Download SDK.
Create a
Plugins
directory at the root of your project.Extract the contents of the Multiplay Game Server SDK into the
Plugins
directory you created in the earlier step.Launch your project (.uproject).
Navigate to Edit > Plugins > Project > Other.
Enable the Multiplay Game Server SDK.
Configure the Multiplay Game Server SDK
Multiplay generates the server.json
file from information about the game server instance, such as the IP address, port number, and server ID. It also includes any configuration variables from the active build configuration.
The Multiplay Game Server SDK uses the server.json
file to access the server query port variable ($$query_port$$
) and the server ID variable ($$serverid$$
).
You can configure the server.json
file in the Multiplayer > Multiplay > Build Configurations section of the Unity dashboard.
You must include at least the queryPort
and the serverID
in the server.json
file for your project. See the following example server.json
file.
{
"queryPort": "$$query_port$$",
"serverID": "$$serverid$$"
}
> Note: See theserver.json
documentation.
Integrate using C++
The following section shows how to integrate with the Multiplay Game Server SDK using Unreal Engine Subsystems.
Three interfaces are available in the Multiplay Game Server SDK:
- Multiplay Server Config Subsystem
- Multiplay Game Server Subsystem
- Multiplay Server Query Handler Subsystem
See Unreal Engine's documentation on Programming Subsystems.
Add the Multiplay Game Server SDK as a dependency
Before continuing, add MultiplayGameServerSDK
as a public dependency of your module, then include the plug-in header files in your classes.
Add MultiplayGameServerSDK
as a dependency of your module to your Unreal project build file:
PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "MultiplayGameServerSDK" });
Include the plug-in header files you wish to access in your own classes:
#include "MultiplayServerConfigSubsystem.h"
#include "MultiplayGameServerSubsystem.h"
#include "MultiplayServerQueryHandlerSubsystem.h"
Multiplay Server Config Subsystem
This subsystem that retrieves the server configuration for the current session.
This subsystem reads the server.json
file and exposes its values via the FMultiplayServerConfig
struct.
FMultiplayServerConfig
has the following values:
- The server ID.
- The allocation ID.
- The Server Query Protocol Port.
- The connection port for the session.
- The directory to write logs to.
UMultiplayServerConfigSubsystem
automatically reads the server.json
file on subsystem initialization.
How to Access UMultiplayServerConfigSubsystem
First, you must get a reference to the subsystem, UMultiplayServerConfigSubsystem is a UGameInstanceSubsystem. You can retrieve it from UGameIns`tance.
UWorld* GameWorld = GetWorld();
UGameInstance* GameInstance = GameWorld->GetGameInstance();
UMultiplayServerConfigSubsystem* ServerConfigSubsystem = GameInstance->GetSubsystem<UMultiplayServerConfigSubsystem>();
GetServerConfig
After you have a reference to the subsystem, retrieve FMultiplayServerConfig
using UMultiplayServerConfigSubsystem::GetServerConfig()
.
For example:
const FMultiplayServerConfig& ServerConfig = ServerConfigSubsystem->GetServerConfig();
UE_LOG(YourLogCategory, Log, TEXT("Server ID: %lld Allocation ID: %s Server Query Port: %u Port: %u Server Log Directory: %s"), ServerConfig.ServerId, *ServerConfig.AllocationId, ServerConfig.QueryPort, ServerConfig.Port, *ServerConfig.ServerLogDirectory)
Multiplay Game Server Subsystem
The Multiplay Game Server Subsystem allows you to subscribe (and respond) to game server events, such as when a game server becomes allocated and when a game server is ready for players. See Game server lifecycle and Server readiness.
You can access the Multiplay Game Server Subsystem by obtaining a reference to the UMultiplayGameServerSubsystem
subsystem. UMultiplayGameServerSubsystem
is a UGameInstanceSubsystem
that you can retrieve from UGameInstance
.
UWorld* GameWorld = GetWorld();
UGameInstance* GameInstance = GameWorld->GetGameInstance();
UMultiplayGameServerSubsystem* GameServerSubsystem =
GameInstance->GetSubsystem<UMultiplayGameServerSubsystem>();
SubscribeToServerEvents
Use the SubscribeToServerEvents()
method to establish a connection between the game server instance and the SDK daemon.
The SDK daemon transmits events to the game server, including OnAllocate and OnDeallocate events. By subscribing to these events, the game server knows when your matchmaker (or another allocating service) allocates and deallocates Multiplay to game sessions.
GameServerSubsystem->SubscribeToServerEvents();
OnAllocate
The OnAllocate
multicast delegate lets the game server know when the game server is allocated. Game server instances must subscribe to the OnAllocate()
callback to know when the instance has been allocated.
Use the OnAllocate()
callback to perform any setup logic necessary when the game server becomes allocated.
GameServerSubsystem->OnAllocate.AddDynamic(this, &UMyClass::OnAllocate);
ReadyServerForPlayers
Use the ReadyServerForPlayers()
method to let Multiplay know that a game server is ready to accept players.
void UMyClass::OnAllocate()
{
// Perform setup logic.
FReadyServerSuccessDelegate OnSuccess;
FReadyServerFailureDelegate OnFailure;
OnSuccess.BindDynamic(this, &UMyClass::OnReadyServerSuccess);
OnFailure.BindDynamic(this, &UMyClass::OnReadyServerFailure);
GameServerSubsystem->ReadyServerForPlayers(OnSuccess, OnFailure);
}
UnreadyServer
Use the UnreadyServer()
method to let Multiplay know that a game server is no longer ready to accept players.
Scenarios in which you might want to use UnreadyServer()
include:
A game match is almost complete
A game match is complete
The game server is full
FUnreadyServerSuccessDelegate OnSuccess; FUnreadyServerFailureDelegate OnFailure; OnSuccess.BindDynamic(this, &UMyClass::OnUnreadyServerSuccess); OnFailure.BindDynamic(this, &UMyClass::OnUnreadyServerFailure); GameServerSubsystem->UnreadyServer(OnSuccess, OnFailure);
OnDeallocate
Use the OnDeallocate
callback to subscribe to deallocation events. You might want to perform any last-minute cleanup or bookkeeping in response to a deallocation event.
> Note: Last-minute cleanup might include collecting telemetry data from the server and beginning the shutdown process by disposing objects and calling RequestExit
to quit the application.
GameServerSubsystem->OnDeallocate.AddDynamic(this, &UMyClass::OnDeallocate);
Multiplay Server Query Handler Subsystem
The Multiplay Server Query Handler Subsystem allows you to set game server variables monitored by the game server query protocol.
> Note: The Multiplay Game Server SDK has a full implementation of Unity’s Server Query Protocol, so the game server only needs to populate the variables. See Server Query Protocol to learn more.
Use the UMultiplayServerQueryHandlerSubsystem
to send the relevant information to the game server’s SQP protocol.
Before using the UMultiplayServerQueryHandlerSubsystem
, you must retrieve it as shown in the following code snippet.
UWorld* GameWorld = GetWorld();
UGameInstance* GameInstance = GameWorld->GetGameInstance();
UMultiplayServerQueryHandlerSubsystem * ServerQueryHandlerSubsystem = GameInstance->GetSubsystem<UMultiplayServerQueryHandlerSubsystem >();
After retrieving the subsystem, you can connect and disconnect to the game server and set and get the game server query values.
Use the set methods to configure all the game server query values:
Use the accessor methods to access the game server query values:
IncrementCurrentPlayers
This API provides a means of atomically increasing the current number of players whenever a player joins the match:
ServerQueryHandlerSubsystem->IncrementCurrentPlayers();
DecrementCurrentPlayers
This API provides a means of atomically decreasing the current number of players whenever a player leaves the match:
ServerQueryHandlerSubsystem->DecrementCurrentPlayers();
SetCurrentPlayers
Use the SetCurrentPlayers()
method to set the number of players connected to the game server. The following example shows how to set the current number of players to 32
.
ServerQueryHandlerSubsystem->SetCurrentPlayers(32);
SetMaxPlayers
Use the SetMaxPlayers()
method to set the maximum number of players allowed to connect to the game server. The following example shows how to set the maximum allowed number of players to 64
.
ServerQueryHandlerSubsystem->SetMaxPlayers(64);
SetServerName
Use the SetServerName()
method to set the game server name. The following example shows how to set the game server name to AwesomeServer
.
ServerQueryHandlerSubsystem->SetServerName(TEXT("AwesomeServer"));
SetGameType
Use the SetGameType()
method to set the game type the game server is running. The following example shows how to set the game type to SearchAndDestroy
.
ServerQueryHandlerSubsystem->SetGameType(TEXT("SearchAndDestroy"));
SetBuildId
Use the SetBuildId()
method to set the game server build ID. The following example shows how to set the build ID to NewBuildId.123.0.1
.
ServerQueryHandlerSubsystem->SetBuildId(TEXT("NewBuildId.123.0.1"));
SetMap
Use the SetMap()
method to set the game server map name. The following example shows how to set the game map to MAP_TD_Dusthill
.
ServerQueryHandlerSubsystem->SetMap(TEXT("MAP_TD_Dusthill"));
SetPort
Use the SetPort()
method to set the game server port number. The following example shows how to set the game server port to 8080
.
ServerQueryHandlerSubsystem->SetPort(8080);
> Note:This is the port number from which the game client can connect to the game server. It's separate from the query port number.
It’s best to continuously update these values throughout the duration of the game. Keeping the values as up-to-date as possible ensures Multiplay collects and displays data while the server is running. After setting all the values, you can make a call to Connect()
.
Connect
Use the Connect()
method to connect to the game server.
ServerQueryHandlerSubsystem->Connect();
GetCurrentPlayers
Use the GetCurrentPlayers()
method to get the number of players connected to the game server.
int32 CurrentPlayers = ServerQueryHandlerSubsystem->GetCurrentPlayers();
GetMaxPlayers
Use the GetMaxPlayers()
method to get the maximum number of players allowed on the game server.
int32 MaxPlayers = ServerQueryHandlerSubsystem->GetMaxPlayers();
GetServerName
Use the GetServerName()
method to get the game server name.
FString ServerName = ServerQueryHandlerSubsystem->GetServerName();
GetGameType
Use the GetGameType()
method to get the game server type.
FString GameType = ServerQueryHandlerSubsystem->GetGameType();
GetBuildId
Use the GetBuildId()
method to get the ID of the build the game server is running.
FString BuildId = ServerQueryHandlerSubsystem->GetBuildId();
GetMap
Use the GetMap()
method to get the active map of the game server.
FString Map = ServerQueryHandlerSubsystem->GetMap();
GetPort
Use the GetPort()
method to get the port number of the game server.
> Note: This is the port number from which the game client can connect to the game server. It's separate from the query port number.
int32 Port = ServerQueryHandlerSubsystem->GetPort();
Disconnect
Use the Disconnect()
method to disconnect from game server updates. After you disconnect from the server, you no longer receive updates about the game server, such as allocation and deallocation events.
ServerQueryHandlerSubsystem->Disconnect();
Integrate using Blueprints
The following section shows how to integrate with the Multiplay Game Server SDK using the Blueprint Visual Scripting system in Unreal Engine.
The Multiplay Game Server SDK can interact with the following interfaces:
Install the Multiplay Game Server SDK plug-in
Make sure the Multiplay Game Server SDK plugin is properly installed before proceeding.
Multiplay Server Config Subsystem
This subsystem has the server configuration for the current session.
This subsystem retrieves this information from the server.json
file on subsystem initialization.
You can retrieve the server configuration by placing a UMultiplayServerConfigSubsystem
node and accessing the Server Config variable.
Server Config has the following values:
- The server ID
- The allocation ID
- The Server Query Protocol Port
- The connection port for the session
- The directory in which the game server saves log files
Multiplay Game Server Subsystem
The Multiplay Game Server Subsystem allows you to subscribe (and respond) to game server events, such as when a game server becomes allocated and when a game server is ready for players. See Game server lifecycle and Server readiness.
> Note: The Multiplay Game Server SDK has a full implementation of Unity’s Server Query Protocol, so the game server only needs to populate the variables. See Server Query Protocol.
Use the instance of UMultiplayGameServerSubsystem
to interact with the Multiplay Game Server Subsystem through the following Blueprints:
SubscribeToServerEvents
After you have an instance of UMultiplayGameServerSubsystem
, you can use the Subscribe Blueprint to subscribe to Multiplay events, including OnAllocate, ServerReady, ServerUnready, and OnDeallocate.
After subscribed to events, the game server must wait for an allocation. Use the OnAllocate Blueprint to enable the game server to know when it has been allocated.
OnAllocate
Use the OnAllocate Blueprint as an opportunity to perform any setup logic necessary before players can join the game server for a game match, such as loading game assets and starting backfill with ReadyServerForPlayers.
After performing any setup logic to allow players to join the game server, you can inform Multiplay that the game server is ready to accept players with the ReadyServer Blueprint.
ReadyServerForPlayers
Use the ReadyServer Blueprint to let Multiplay know when a game server is ready to accept players for a game match.
If at any point the state of the game match changes so that you no longer want to accept new players, use the UnreadyServer Blueprint to let Multiplay know that the game server is no longer ready to accept players.
UnreadyServer
Use the UnreadyServer Blueprint to let Multiplay know that the game server is no longer ready to accept players.
Scenarios in which you might want to use the UnreadyServer Blueprint include:
- A game match is almost complete
- A game match is complete
- The game server is full
OnDeallocate
Use the OnDeallocate Blueprint to know when Multiplay is deallocating the game server. The OnDeallocate Blueprint provides an opportunity to perform any last-minute cleanup or bookkeeping necessary before the game server shuts down.
Multiplay Server Query Handler Subsystem
The Multiplay Server Query Handler Subsystem allows you to set game server variables monitored by the game server query protocol. This implementation uses SQP. See Server Query Protocol.
You can use the UMultiplayServerCheckSubsystem
to:
- Connect to game servers
- Disconnect from game servers
- Configure game server query values using the setting Blueprints
- Access game server query values using the accessor Blueprints
Setting Blueprints
Use the following setting Blueprints to set the query values for the game server. These setting Blueprints include SetCurrentPlayers, SetMaxPlayers, SetServerName, SetGameType, SetBuildId, SetMap, and SetPort.
SetCurrentPlayers
Use the SetCurrentPlayers Blueprint to set the number of players connected to the game server.
SetMaxPlayers
Use the SetMaxPlayers Blueprint to set the maximum number of players that can connect to the game server.
SetServerName
Use the SetServerName Blueprint to set the current name of the game server.
SetGameType
Use the SetGameType Blueprint to set the current game the game server.
SetBuildId
Use the SetBuildId Blueprint to set the current build ID of the game server.
SetMap
Use the SetMap Blueprint to set the current map of the game server.
SetPort
Use the SetPort Blueprint to set the port number of the game server.
> Note: This is the port number from which the game client can connect to the game server. It's separate from the query port number.
Make sure to continuously update these values as they're bound to change during the game. This ensures Multiplay collects and displays data while the server is running. After setting all the values, you can add the Connect Blueprint.
Connect Blueprint
Use the Connect Blueprint to establish a connection to the game server. You must establish a connection to the game server before using any of the accessor Blueprints.
Accessor Blueprints
Use the following accessor Blueprints to access the values you set. These accessor Blueprints include GetCurrentPlayers, GetMaxPlayers, GetServerName, GetGameType, GetBuildId, GetMap, and GetPort.
GetCurrentPlayers
Use the GetCurrentPlayers accessor Blueprint to get the current number of players connected to the game server.
GetMaxPlayers
Use the GetMaxPlayers accessor Blueprint to get the maximum number of players allowed to connect to the game server.
GetServerName
Use the GetServerName accessor Blueprint to get the current name of the game server.
GetGameType
Use the GetGameType accessor Blueprint to get the current game the game server.
GetBuildId
Use the GetBuildId accessor Blueprint to get the ID of the build the game server is running.
GetMap
Use the GetMap accessor Blueprint to get the current map of the game server.
GetPort
Use the GetPort accessor Blueprint to get the current port of the game server.
> Note: This is the port that the game client uses to connect to the game server, not the query port.
Disconnect Blueprint
Use the Disconnect Blueprint to disconnect from the game server before shutting it down.