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 handle error cases in a communicative, player-friendly way.

Multiplayer Flow Overview #

The following graphic and numbered list present a simplified overview of how Pragma Engine facilitates Multiplayer 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 Match Capacity 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 serviceTracks 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.
Match Capacity 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.
Game Server Compatibility PluginDetermines whether a group of players can play a game together on a common GameServerVersion.
Matchmaking PluginContains all matchmaking logic.
Game Instance PluginPrepares custom data about the game instance.
Game Instance Matchmaking PluginPrepares custom data about a game instance that is entering matchmaking.
Capacity Provider PluginFacilitates allocating a game server for the players.

Game Server #

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

Game Server Protocol Configuration #

The Pragma game server SDK supports both WebSocket and HTTP web protocols.

WebSockets are the recommended option. Note that WebSocket connections are required for the Add parties and players to active game instances feature.

A valid HTTP use case would be to support websites interacting with Partner endpoints.

By default, the Pragma game server SDK uses WebSockets. To modify this behavior to use HTTP instead, override the SDK config to set the partnerProtocolType to HTTP.

Below are examples for overriding the protocol to enable HTTP for both Unreal and Unity.

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

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