Connect Game Servers to Pragma Backend #

This topic provides instructions on how to establish a link between the allocated game server and the appropriate game instance on the Pragma backend.

Provide SDK with partner tokens and address #

To use the Pragma SDK, the game server has to provide it with the partner tokens and partner backend address. There are several ways to accomplish this:

Setting programmatically:

auto Runtime = Subsystem->Runtime();
Runtime->Config().PartnerBackendAddress = "http://HOSTNAME:PORT";
Runtime->Config().PartnerSessionSocialAuthToken = "PARTNER_SOCIAL_TOKEN";
Runtime->Config().PartnerSessionGameAuthToken = "PARTNER_GAME_TOKEN";

PragmaSessionManager.SetConfig(new SdkConfig.Data
{
    partnerBackendAddress = "http://HOSTNAME:PORT",
    partnerSessionSocialAuthToken = "PARTNER_SOCIAL_TOKEN",    
    partnerSessionGameAuthToken = "PARTNER_GAME_TOKEN"
});

Adding command-line arguments to your game server executable:

C:/path/to/server.exe -PragmaPartnerBackendAddress=<http://HOSTNAME:PORT> -PragmaPartnerSessionSocialAuthToken=<PARTNER_SOCIAL_TOKEN> -PragmaPartnerSessionGameAuthToken=<PARTNER_GAME_TOKEN>

Using config files:

Put the following in the appropriate configuration file (e.g., DefaultGame.ini for Unreal or Pragma.json for Unity):

[/Script/PragmaSdk.PragmaSdkConfig]
PartnerBackendAddress = "http://HOSTNAME:PORT";
PartnerSessionSocialAuthToken = "PARTNER_SOCIAL_TOKEN";
PartnerSessionGameAuthToken = "PARTNER_GAME_TOKEN";

{
  "partnerBackendAddress": "http://HOSTNAME:PORT",
  "partnerSessionSocialAuthToken": "PARTNER_SOCIAL_TOKEN",
  "partnerSessionGameAuthToken": "PARTNER_GAME_TOKEN"
}

Establish WebSockets #

To establish a connection using the WebSocket protocol, get the Pragma server object and then call Connect().

const auto* Subsystem = GetWorld()->GetGameInstance()->GetSubsystem<UPragmaGameServerSubsystem>();
auto Runtime = Subsystem->Runtime();

// Optionally, set configurations on the Runtime
Runtime->Config().PartnerBackendAddress = "http://127.0.0.1:10000";

auto Server = Runtime->Server();
Server->Connect(FServer::FConnectedDelegate::CreateLambda([this]
{
    ...
}));

var runtime = Runtime.Get();

// Optionally, set configurations on the Runtime
runtime.Config.ConfigData.partnerBackendAddress = "http://127.0.0.1:10000";

var server = runtime.Server();
var connectPromise = new Promise();
server.Connect(connectPromise.Complete);
yield return connectPromise.Future;
...

Link to game instance #

Link the game server with the game instance.

When the game server is allocated and communication with the Pragma backend is established, the game server needs to link to the appropriate game instance. To do so, the game server needs to call MatchApi.RequestStartGame(). On success, this call triggers the OnGameStart event, which provides a GameStart object that includes a list of players and custom data.

Server->MatchApi().OnGameStart.AddUObject(
	this, &AMyPlayerController::HandleOnGameStart);

Server->MatchApi()->RequestStartGame(GameInstanceId);

Server.MatchApi.OnGameStart += HandleOnGameStart;

Server.MatchApi.RequestStartGame(GameInstanceId);

Configure keep-alive values #

When the keep-alive service is enabled (default), game servers are required to send heartbeats at specified intervals to Pragma Engine. This allows Pragma Engine to confirm that the game instance and game server are still operational.

Game servers using the Pragma SDKs automatically send keep-alive signals to Pragma Engine when this feature is enabled.

To customize keep-alive features, edit the following values in the GameInstanceServiceConfig block of your config file:

• enableKeepAlive: When true, enables the keepalive feature (default: true)
• keepAliveIntervalMillis: Interval, in milliseconds, to wait between keepalive requests (default: 30000 milliseconds)
• keepAliveMissesLimit: Number of keepalive requests that can be missed before releasing the game instance from the service (default: 3)

For example:

  serviceConfigs: 
    GameInstanceServiceConfig:
      enableKeepAlive: true
      keepAliveIntervalMillis: 30000
      keepAliveMissesLimit: 3

As a best practice, we recommend against disabling the keep alive feature, as it’s critical for game flow health.

If a game server fails to send a keep-alive RPC within the configured timeout, the Game Instance plugin onGameServerDisconnect() method is called.

Handle game server disconnects #

Using the Game Instance plugin onGameServerDisconnect() method, you can define additional actions that should occur when a game server disconnects from Pragma while linked to an active game instance.

suspend fun onGameServerDisconnected(
    readOnlyGameInstance: ReadOnlyGameInstance) {
}

The readOnlyGameInstance is a read-only version of the GameInstance class.