Game Server Hosting SDK for Unreal Engine#

The Multiplay Game Server SDK for Unreal Engine includes all the functionality necessary to leverage Multiplay scaling and game server services in 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:

1. Create an Epic Games account.
2. Create a GitHub account.
3. Link your Epic Games account to GitHub account.
4. Clone the Unreal Engine source code using Git.
5. Check out a branch corresponding to one of the engine versions specified above (for example, 4.27).
6. 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:

1. Download the Multiplay Game Server SDK plug-in.

   1. From the Unity Dashboard, select Multiplayer on the left.
   2. Select Multiplayer > Game Server Hosting > Packages & SDKs.
   3. Select Download SDK.

2. Create a Plugins directory at the root of your project.

3. Extract the contents of the Multiplay Game Server SDK into the Plugins directory you created in the earlier step.

4. Launch your project (.uproject).

5. Navigate to Edit > Plugins > Project > Other.

6. 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$$"
}

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.

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.

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:

• SetCurrentPlayers
• SetMaxPlayers
• SetServerName
• SetGameType
• SetBuildId
• SetMap
• SetPort

Use the accessor methods to access the game server query values:

• GetCurrentPlayers
• GetMaxPlayers
• GetServerName
• GetGameType
• GetBuildId
• GetMap
• GetPort

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);

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.

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:

• Multiplay Game Server Subsystem
• Multiplay Server Query Handler Subsystem

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.

Use the instance of UMultiplayGameServerSubsystem to interact with the Multiplay Game Server Subsystem through the following Blueprints:

• Subscribe
• OnAllocate
• ReadyServer
• UnreadyServer
• OnDeallocate

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.

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.

Disconnect Blueprint#

Use the Disconnect Blueprint to disconnect from the game server before shutting it down.