Connect Players to a Game Server #

This topic provides instructions on connecting players with the game server hosting their game instance.

Connect players #

After establishing a connection with the Pragma backend, the game server can call MatchApi.ConnectPlayers() to indicate that it’s ready for players to connect to the game server.

Players receive a OnHostConnectionDetailsReceived notification, which includes host connection details such as host name, port, game instance ID, the ExtPlayerConnectionDetails payload (which can be used to define custom game server host information), and a unique set of partner session tokens.

Server->MatchApi()->ConnectPlayers(
  const FString& GameInstanceId,
  const TArray<FPragma_GameInstance_PlayerConnectionDetails>& PlayerConnectionDetails,
  const FString& Hostname,
  const int Port,
  const FOnCompleteDelegate& OnComplete
);

Server.MatchApi.ConnectPlayers(
  PragmaId gameInstanceId,
  IEnumerable<PlayerConnectionDetails> playerConnectionDetails, 
  string hostname, 
  int port,
  CompleteDelegate onComplete
);

Verify player connection tokens #

Using player connection tokens, Pragma Engine can determine whether a specific player can connect to a specific game server. The player verification process is optional, but recommended for competitive games.

When a game server links to a game instance, each player in the game instance receives a unique connection token along with host connection details. The player sends the connection token to the game server, at which point the game server forwards the token to the engine via MatchApi.VerifyPlayer(). If the engine determines the token is valid, players can connect to the game server.

Server->MatchApi()->VerifyPlayer(
  const FString& GameInstanceId,
	const FString& PlayerId,
	const FString& ConnectionToken,
	const FVerifyPlayerDelegate& OnComplete
);

Server.MatchApi.VerifyPlayer(
  PragmaId gameInstanceId, 
  PragmaId playerId, 
  string connectionToken,
  VerifyPlayerDelegate onComplete
);

Configure player connection timeout #

Game servers must connect players within 30 seconds of the game server linking with the game instance. To alter this value, set the connectPlayersTimeoutMillis config value.

The timer starts in the following scenarios:

• a game server is initially linked to a game instance
• new players are added to the game instance

If the game server does not call MatchApi.ConnectPlayers() within the time frame defined by connectPlayersTimeoutMillis one of the following occurs:

• If attempting to add initial players, the Game Instance plugin onGameServerFailedToConnectInitialPlayers() method is called, players are released from the game instance, and the game instance is terminated.
• If attempting to add additional players to a game instance, the Game Instance plugin onGameServerFailedToConnectMorePlayers() method is called and the players attempting to connect are released from the game instance.

Handle player connection timeouts #

Using the Game Instance plugin onGameServerFailedToConnectInitialPlayers() or onGameServerFailedToConnectMorePlayers() method, you can define additional actions that should occur when game servers fail to connect players within the time frame defined by connectPlayersTimeoutMillis.

suspend fun onGameServerFailedToConnectInitialPlayers(
    readOnlyGameInstance: ReadOnlyGameInstance,
    initialPlayers: List<ReadOnlyGamePlayer>
) {
}

suspend fun onGameServerFailedToConnectMorePlayers(
    readOnlyGameInstance: ReadOnlyGameInstance,
    morePlayers: List<ReadOnlyGamePlayer>
) {
}

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

Reconnect players #

The Game Instance service keeps track of game server connection details, allowing players to reconnect to the server hosting their game at any time. If players become disconnected from their game, they can reconnect by doing the following:

1. If necessary, reconnect to Pragma Engine
2. If reconnecting due to logging out, call GameInstanceApi.Initialize()
3. Call one of the GameInstanceApi GameInstanceCache functions:

• GetGameInstances(): use to fetch an array of the player’s game instances. Each item has a GetHostConnectionDetails() method.
• GetFirstGameInstance.GetHostConnectionDetails(): use if the player only has one game instance
• GetGameInstance(gameInstanceId).GetHostConnectionDetails(): use to fetch host connection details for a specific game instance

For example, to use the Game Instance API for Unreal to fetch host connection details for a game instance identified by gameInstanceId, do the following:

PragmaPlayer->GameInstanceApi().GetGameInstanceCache()->GetGameInstance(gameInstanceId)
    ->GetHostConnectionDetails();

Manage game server compatibility #

Define compatibility maps for game servers

Game servers and clients must be updated in parallel as updates are added to live service games. Pragma Engine checks for server/client compatibility whenever a party changes (players added/removed, party enters matchmaking, etc.).

Pragma specifies a defaultGameServerVersion in the dev-defaults.yml config as a fallback configuration for all game client versions.

You can define a list of game server versions and corresponding compatible game client versions in the gameServerVersionCompatibility block of your config file. Unique compatibility keys (positive integers) define the priority of the server/client version mappings. Each mapping includes:

• server version
• one or more corresponding client versions. Note that this value can contain a wildcard character (*).
• unique compatibility keys (positive integers) that define the priority of the client version. Higher numbers indicate higher priority.

The following is an example PartyConfig configuration block:

game:
  core:
  serviceConfigs:
    PartyConfig:
        gameServerVersionCompatibility:
          1:
            serverVersion: "server0"
            clientVersions:
              1: "client0-*"
              2: "client1-*"
              3: "client2-pc"
          2:
            serverVersion: "server1"
            clientVersions:
              1: "client1-*"
              2: "client2-ps4"
              3: "client2-xbox"
              4: "client3-*"

If any player client in the party is incompatible with the server version, the player client(s) with incompatible client versions will receive the OnGameClientVersionUpdateRequired notification. Every player in the party will receive the OnPartyClientVersionMismatch notification. If all player clients are supported but cannot match to the same game server, all players will receive the OnPartyClientVersionMismatch notification.

The only action Pragma Engine prevents as a result of server/client version mismatch is entering matchmaking. If a party with mismatched server/client versions attempts to enter matchmaking, Pragma Engine throws an error and does not allow add the party to the matchmaking queue.

If you want to override the game server version mapping, configure your party plugin to set the party’s overrideGameServerVersion value to true and manually set thegameServerVersion value.

Related events and errors #

Related events:

• OnPartyUpdated
• OnGameClientVersionUpdateRequired
• OnPartyClientVersionMismatch
• OnHostConnectionDetailsReceived

Related errors:

• PartyService_NotInParty

• GameInstanceService_UnknownGameInstanceId
• GameInstanceService_MissingPlayerConnectionDetails
• GameInstanceService_PlayerNotInGameInstance