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.Link().

On success, the delegate contains a GameStart object that includes a list of players and custom data.

Server->MatchApi().Link(
  GameInstanceId,
  UPragmaMatchApi::FGameStartDataDelegate::CreateLambda(
    [this](const TPragmaResult<>& Result)
    {
      if (Result.IsSuccess())
      {
        //...
      }
      else
      {
        //...
      }
    })
);

Server.MatchApi.Link(gameInstanceId, result => 
{
  if (result.IsSuccessful)
  {
    //...
  }
  else
  {
    //...
  }
});

When a game server calls Link() for a game instance that used to have a game server, all players are provided to the new game server as initial players.

Unlink game instance #

You can explicitly unlink a game server from a game instance using the MatchAPi.Unlink() method. Use this when you want to spin down a game server but keep a collection of players together in a game instance.

Server->MatchApi().Unlink(
  GameInstanceId,
  UPragmaMatchApi::FOnCompleteDelegate::CreateLambda(
    [this](const TPragmaResult<>& Result)
    {
      if (Result.IsSuccess())
      {
        //...
      }
      else
      {
        //...
      }
    })
);

Server.MatchApi.Unlink(gameInstanceId, result =>
{
  if (result.IsSuccessful)
  {
    //...
  }
  else
  {
    //...
  }
});

The Unlink() method triggers the Game Instance plugin handleGameServerUnlinkRequest(), which accepts a snapshot of the game instance and an ExtGameServerUnlinkRequest payload. Use this method to apply custom behavior in response to the unlinking.

suspend fun handleGameServerUnlinkRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    requestExt: ExtGameServerUnlinkRequest
) {
  //...
}

After a game server is unlinked from a game instance, players will receive a OnGameInstanceUpdated event that does not contain any host connection details.

You can re-allocate a new game server using the allocateGameServer() method. See Allocate Game Servers for instructions.

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 onGameServerDisconnected() method is called.

Handle game server disconnects #

Using the Game Instance plugin onGameServerDisconnected() method, you can define additional actions that should occur when a game server disconnects from Pragma while linked to an active game instance. By default, this method terminates a game instance with the GAME_SERVER_DISCONNECTED reason.

suspend fun onGameServerDisconnected(
    gameInstanceSnapshot: GameInstance.GameInstance,
) {
    gameInstanceSnapshot.terminate(
      GameInstanceTerminationReason.GAME_SERVER_DISCONNECTED)
}

When a game is terminated, players will receive the OnGameInstanceTerminated event with the termination reason.

You can re-allocate a new game server using the allocateGameServer() method. See Allocate Game Servers for instructions.