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:

Refer to Programming Subsystems (Unreal Engine).

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 MultiplayServerConfig struct.

MultiplayServerConfig 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.

MultiplayServerConfigSubsystem automatically reads the server.json file on subsystem initialization.

How to Access UMultiplayServerConfigSubsystem

First, you must get a reference to the subsystem, MultiplayServerConfigSubsystem is a GameInstanceSubsystem. You can retrieve it from GameInstance.

UWorld* GameWorld = GetWorld();
UGameInstance* GameInstance = GameWorld->GetGameInstance();
UMultiplayServerConfigSubsystem* ServerConfigSubsystem = GameInstance->GetSubsystem<UMultiplayServerConfigSubsystem>();

GetServerConfig

After you have a reference to the subsystem, retrieve MultiplayServerConfig using MultiplayServerConfigSubsystem::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. Refer to Game server lifecycle and Server readiness.

You can access the Multiplay Game Server Subsystem by obtaining a reference to the MultiplayGameServerSubsystem subsystem. MultiplayGameServerSubsystem is a GameInstanceSubsystem that you can retrieve from GameInstance.

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.

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.

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. Refer to Server Query Protocol to learn more.

Use the Multiplay Server Query Handler Subsystem to send the relevant information to the game server’s SQP protocol.

Before using the Multiplay Server Query Handler Subsystem, 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

IncrementCurrentPlayers() provides a means of atomically increasing the current number of players whenever a player joins the match:

ServerQueryHandlerSubsystem->IncrementCurrentPlayers();

DecrementCurrentPlayers

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

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.

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();
Unity logo Documentation
Copyright © 2024 Unity Technologies
"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.