Multiplayer #

Pragma Engine Multiplayer services manage the workflow for connecting players with their friends, matching with other players, and getting into a game.

Game Flow

A successful game flow consists of several stages, from partying up to playing a game to completing a match. 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 how to handle error cases in a communicative, player-friendly way.

Description #

Below is a simplified overview of how Pragma Engine facilitates Multiplayer services.

  1. Players create parties and make selections.

    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 groups parties together to form complete teams. In PVP games, the Matchmaking service matches parties of different teams to form matches.

  3. Game server is allocated.

    Once matches are formed, the Matchmaking service hands the match to the Match Lifecycle service. The Match Capacity service keeps track of game server capacity and number of matches allocated. It finds an available game server or provisions an additional server if everything is at capacity.

  4. Connection details are sent and match starts.

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

  5. Match end data is processed.

    When the match ends, the game server communicates match end results to the Match Lifecycle service, which processes and logs this data (such as item granting and player stats tracking).

  6. Match end updates are sent.

    The Match Lifecycle service sends a notification to players with match end updates. Players remain in their existing parties.

Bindable Events #

Besides the typical RPC calls, there are several events that player clients can listen to. These events typically fire in cases where someone in the party makes a change.

The table in the dropdown below contains all Multiplayer bindable events along with associated descriptions of when the event is triggered. All bindable events are currently stored on the Party service for ease of access.

SDK Events
UnrealUnitytrigger
FPartyEvent OnPartyChanged;public event Action<IParty> OnPartyDataChanged;When any party information changes, including creation and destruction.

Note: All other On* events fire in addition to this one, so developers will need to account for handling multiple events at once.
FPlayerEvent OnPlayerChanged;public event Action<IPartyPlayer> OnPlayerDataChanged;When any player information changes.
FInviteEvent OnInviteReceived;public event Action<PartyInvite> OnInviteReceived;When a party invite is received from another player.
FInviteListEvent OnInvitesChanged;public event Action<IReadOnlyList<PartyInvite>> OnInvitesChanged;When the invite list is changed.
FInviteCodeEvent OnInviteCodeChanged;public event Action<string> OnInviteCodeChanged;When an invite code changes.
FInviteIdEvent OnInviteAccepted;public event Action<PragmaId> OnInviteAccepted;When an invite is accepted (inviter only).
FInviteIdEvent OnInviteDeclined;public event Action<PragmaId> OnInviteDeclined;When an invite is declined (inviter only).
FInviteIdEvent OnInviteRevoked;public event Action<PragmaId> OnInviteRevoked;When a party invite is revoked, such as when pending invites are canceled by a game starting a match.
FPartyEvent OnPartyJoined;public event Action<IParty> OnPartyJoined;When a party invite is revoked, such as when pending invites are canceled by a game starting a match.
FPlayerEvent OnPlayerJoined;public event Action<IPartyPlayer> OnPlayerJoined;When a player joins a party (entire party).
FPlayerLeftEvent OnPlayerLeft;public event Action<PragmaId> OnPlayerLeft;When a player leaves a party (entire party).
FPartyLeftEvent OnPartyLeft;public event Action OnPartyLeft;When a player leaves a party by voluntarily choosing to leave.
FRemovedFromPartyEvent OnRemovedFromParty;public event Action<RemovalReason> OnRemovedFromParty;When a player leaves a party for reasons outside of their control.
FPlayerListEvent OnPlayersChanged;public event Action<IReadOnlyList<IPartyPlayer>> OnPlayersChanged;When one or more players join or leave a party.

Note: Still fires even if the overall number stays the same (i.e. +1, -1 in a single update).
FPartySelectionsEvent OnExtPartySelectionsChanged;public event Action<ExtPartySelections> OnExtPartySelectionsChanged;When a party’s public selections change.
FPrivatePlayerSelectionsEvent OnExtPrivatePlayerSelectionsChanged;public event Action<ExtPrivatePlayerSelections> OnExtPrivatePlayerSelectionsChanged;When a player’s own private selections change.
FMatchmakingFailureV1NotificationEvent OnMatchmakingFailureNotification;public event Action<MatchmakingFailureReason> OnMatchmakingFailed;When a party is removed from matchmaking.
FPreferredGameServerZonesEvent OnPreferredGameServerZonesChangedpublic event Action<List<string>> OnPreferredGameServerZonesChanged;When the preferred game server zones change.
FUpdateClientVersionEvent OnGameClientVersionUpdateRequired;public event Action OnGameClientVersionUpdateRequired;When a client needs an updated GameClientVersion.
FEnteredMatchmakingEvent OnEnteredMatchmaking;public event Action OnEnteredMatchmaking;When the party has entered matchmaking.
FLeftMatchmakingEvent OnLeftMatchmaking;public event Action OnLeftMatchmaking;When the party has left matchmaking.
FMatchIdEvent OnMatchFound;public event Action<PragmaId> OnMatchFound;When the match is formed from matchmaking but before the game server is ready.
FMatchIdEvent OnMatchIdChanged;public event Action<PragmaId> OnMatchIdChanged;When the MATCH_ID changes.
FFailedToFindMatch OnFailedToFindMatch;public event Action OnFailedToFindMatch;When match allocation fails due to game server issues after matchmaking succeeds.
FMatchReadyEvent OnMatchReady;public event Action<MatchReadyV1Notification> OnMatchReady;When a game server has started a match and is available for parties to connect.
FMatchProcessedEvent OnMatchProcessed;public event Action<MatchProcessedV3Notification> OnMatchProcessed;When a match result is processed.
FMatchReconnectEvent OnMatchReconnect;public event Action<MatchReconnectV1Notification> OnMatchReconnect;When connecting to the platform after disconnecting during a match.
FMatchTerminationEvent OnMatchTermination;public event Action<MatchTerminationV1Notification> OnMatchTermination;When a match is forcibly terminated because it’s no longer communicating with the engine.

Components #

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

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.

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 grouping parties together to form complete teams and matching teams against each other.
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.
Match Lifecycle 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 matches.
Match Capacity serviceKeeps track of the status of game servers in order to allocate a match on an available game server.

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

Pragma Engine Multiplayer Plugins #

PluginDescription
PartyPluginEnables the customization of in-party behaviors.
GameServerCompatibilityPluginDetermines whether a group of players can play a match together on a common GameServerVersion.
MatchmakingStrategyContains all matchmaking logic.
MatchEndPluginEnables the customization of match end player data update processing.
MatchFoundPluginEnables ext customization of match details prior to starting the match. Enables ext customization of connection details received from game server prior to communicating the connection details to players.

Game Server #

This is the software responsible for everything a player sees and does while playing a match. 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 matches to the backend, and will receive matches to start via this polling flow. The game server is then expected to report match ready for these matches. The Pragma SDK provides functionality to assist with making these HTTP calls.

Protocol Configuration #

Pragma Engine supports both WebSocket and HTTP web protocols for the Connect() call from the SDK.

WebSockets are the recommended option. Note that WebSocket connections are required for the Active Match feature.

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

By default, Pragma Engine 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.

auto Runtime = FRuntime::Create();
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
    );
}

Topics in This Section #

TopicDescription
PartyAllows players to create a party with their friends and configure their game before entering matchmaking.
MatchmakingConnect parties to create matches. Utilizes game mode and queue configuration, matchmaking rules, and matchmaking.
SessionTracks the player's current status within Pragma Engine.
Match LifecycleTrack in-progress matches, receive match events from the game server, and execute all match end processing.
Match CapacityProcess match requests and coordinate with a game server management provider to allocate game servers.
Match EndGrant content, update quests and progression data, and grant rewards.
Error HandlingCommon errors for Multiplayer services.