Multiplayer #

Pragma Engine Multiplayer services manage the workflow for grouping players into parties, matching parties, 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.

Multiplayer

  1. Players create parties and make selections.

    Using the Party service, players can create a party and invite other players 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. Your fleet management solution (such as the Pragma-provided Fleet service) should keep track of game server capacity and the number of game instances allocated. The fleet manager is responsible for finding an available game server or provisioning 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 Unreal and Unity) 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.

ServiceDescription
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 custom plugins.

Pragma Engine multiplayer plugins #

PluginDescription
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 = "http://127.0.0.1:10000";
Runtime->Config().PartnerProtocolType = EPragmaProtocolType::Http;
auto Server = Runtime->Server();
Server->Connect(FServer::FConnectedDelegate::CreateLambda([this]
{
    // OnComplete delegate
}));
PragmaSessionManager.SetConfig(new SdkConfig.Data
{
    partnerBackendAddress = _gameConfig.PragmaBackendAddress,
    partnerSessionGameAuthToken = _gameConfig.PartnerGameToken,
    partnerSessionSocialAuthToken = _gameConfig.PartnerSocialToken,
    partnerProtocolType = ProtocolType.Http
   
});
var connectPromise = new Promise();
_session.Connect(connectPromise.Complete);
yield return connectPromise.Future;
if (connectPromise.Future.Result.IsFailure)
{
    db.Error(
      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 #

TopicDescription
PartyLearn about the Party service, which allows players to create a party and configure game settings before entering matchmaking
MatchmakingLearn about the Matchmaking service, which matches parties using game modes, queue configuration, and matchmaking rules
Game InstanceLearn about the Game Instance service, which allows users to track in-progress game instances, receive events from the game server, and execute end of game processing
Fleet ManagementLearn about fleet management, including using the optional Pragma Fleet service to process game instance requests and coordinate with a game server management provider to allocate game servers
SessionLearn about the Session service, which tracks the player's current status within Pragma Engine
Error HandlingCommon errors for Multiplayer services