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:

  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 MultiplayerGame Server HostingPackages & 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.

Unreal Engine SDK page in the Unity Dashboard

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:

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:

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.