Multiplayer #

Pragma Engine Multiplayer services manage the workflow for connecting players with their friends, matching with other players, and getting into a game. A successful game flow consists of several stages, from partying up to playing a game to completing a game instance. While ideally players will consistently travel through a preset flow, Multiplayer services must not only build out a success path, but must also account for potential issues caused by external services such as game server providers and ISPs. In this section, we’ll take a look at the pieces that make up Multiplayer services and explain how to customize and leverage the various features.

Multiplayer Flow Overview #

The following graphic and numbered list present a simplified overview of how Pragma Engine facilitates Multiplayer services. Items in blue represent Pragma services.


  1. Players create parties and make selections.

    Using the Party service, players can create a party and invite friends to join; solo players are parties of one. Within the party, players can coordinate with each other and make pregame party and player-specific selections.

  2. Parties enter matchmaking and are matched with opponents.

    When players are ready, a party leader can enter the party into matchmaking. The Matchmaking service uses custom logic to compare parties to form appropriate matches to send to the game server.

  3. Game server is allocated.

    Once matches are formed, the Matchmaking service creates a New Game Instance. The Fleet service service keeps track of game server capacity and number of game instances allocated. It finds an available game server or provisions an additional server if everything is at capacity.

  4. Connection details are sent and game instance starts.

    The chosen game server communicates with the Game Instance service to get game details. The Game Instance service sends connection information back to involved players, who connect to the waiting server. Once all players connect, the game instance starts.

  5. Game instance end data is processed.

    When the game instance ends, the game server communicates results to the Game Instance service, which processes and logs this data (such as item granting and player stats tracking).

  6. Game instance end updates are sent.

    The Game Instance service sends a notification to players with game instance results. Players remain in their existing parties.

Multiplayer Components #

Let’s take a look at the various components that must work together for a successful game flow.

Player Client #

This is the software running on a player’s machine, which is how a player experiences a game. The player client is responsible for everything the player sees, and for sending and receiving data from your game service, which consists of Pragma Engine, your game server, and any other in-house or third party services you might be using. While studios are responsible for authoring the game client, we provide the Pragma SDK (for Unity and Unreal) so that your game client can communicate with Pragma Engine.

Pragma Engine Services #

The engine has several services and plugins working in concert to get players matched up and playing.

Party serviceAllows players to group up and make pregame selections. These pregame selections may include settings such as difficulty, game mode, characters, or cosmetics.
Matchmaking serviceResponsible for comparing parties to form appropriate matches to send to the game server.
Session serviceHelps with disconnection logic by tracking the player’s current status with Pragma Engine, such as their party/match/game ID and if they are joining a party, looking for a match, or playing a game.
Game Instance serviceThe middleman between the various services. Responsible for coordinating everything that happens after the Matchmaking service successfully finds a match, such as requesting the start of a game session, communicating connection information to game clients, and processing the results of completed game instances.
Fleet serviceKeeps track of the status of game servers in order to allocate a game instance on an available game server.

Some of these behaviors can be customized or extended through various authored plugins.

Pragma Engine Multiplayer Plugins #

Party PluginEnables the customization of in-party behaviors.
Matchmaking PluginContains all matchmaking logic.
Game Instance PluginPrepares custom data about the game instance.
Game Instance Host PluginCalled to prepare any custom data to be used by FleetPlugin.selectServerPool to help select a server pool for the game instance.
Game Instance Matchmaking PluginPrepares custom data about a game instance that is entering matchmaking.
Fleet PluginFacilitates allocating a game server for the players.

Game Server #

Studios are responsible for authoring the game server, which hosts the software responsible for everything a player sees and does while involved in a game instance. The game server is expected to repeatedly report its capacity for hosting game instances to the Pragma Engine backend, and will receive game instances to start via this polling flow. The game server is then expected to report when the game instance is ready. The Pragma SDK provides functionality to assist with making these calls.

To integrate with the Pragma Engine Multiplayer services, a game server will need to interact with the Pragma SDK via WebSockets or HTTP web protocol. Pragma recommends you use Websockets, which the Pragma game server SDK uses by default. Note that WebSocket connections are required adding parties to active game instances.

To use HTTP instead, override the SDK config and set the partnerProtocolType to HTTP, as shown in the following examples. A valid HTTP use case would be to support websites interacting with Partner endpoints.

const auto* Subsystem = GetLocalPlayer()->GetSubsystem<UPragmaLocalPlayerSubsystem>();
auto Runtime = Subsystem->Runtime();
Runtime->Config().BackendAddress = "";
Runtime->Config().PartnerProtocolType = EPragmaProtocolType::Http;
auto Server = Runtime->Server();
    // OnComplete delegate
PragmaSessionManager.SetConfig(new SdkConfig.Data
    partnerBackendAddress = _gameConfig.PragmaBackendAddress,
    partnerSessionGameAuthToken = _gameConfig.PartnerGameToken,
    partnerSessionSocialAuthToken = _gameConfig.PartnerSocialToken,
    partnerProtocolType = ProtocolType.Http
var connectPromise = new Promise();
yield return connectPromise.Future;
if (connectPromise.Future.Result.IsFailure)
      LogTag, "Failed to initialize Server: {0}", connectPromise.Future.Result.ErrorCode

To learn about player client/game server version compatibility, see Manage game server compatibility.

Topics in This Section #

PartyAllows players to create a party with their friends and configure their game before entering matchmaking.
MatchmakingConnects parties to create matches. Utilizes game mode and queue configuration, matchmaking rules, and matchmaking.
Game InstanceAllows users to track in-progress game instances, receive events from the game server, and execute end of game processing.
Fleet ServiceProcesses game instance requests and coordinates with a game server management provider to allocate game servers.
SessionTracks the player's current status within Pragma Engine.
Match CapacityProcesses game instance requests and coordinates with a game server management provider to allocate game servers.
Error HandlingCommon errors for Multiplayer services.