Game Flow #

Game flow describes the workflow for connecting players with their friends, matching with other players, and getting into game.

sequenceDiagram participant Player participant Party as Party Service participant Session as Session Service participant Matchmaking as Matchmaking Service participant MatchLifecycle as Match Lifecycle Service participant MatchCapacity as Match Capacity Service participant GameServer as Game Server Player->>Party: Create party Party->>Session: Add PARTY_ID to party members' sessions Party->>Matchmaking: Enter party to matchmaking Matchmaking->>Session: Set party members IN_MATCHMAKING Matchmaking->>Matchmaking: Match parties Matchmaking->>MatchLifecycle: Start game server MatchLifecycle->>Session: Set party members IN_MATCH MatchLifecycle->>MatchCapacity: Start match GameServer->>MatchCapacity: Report available capacity MatchCapacity->>GameServer: Start these matches GameServer->>MatchLifecycle: Match is ready MatchLifecycle->>Player:Send match details Player->>GameServer:Connect with match details GameServer->>GameServer:Play match GameServer->>MatchLifecycle:Match end MatchLifecycle->>MatchLifecycle: Process match end MatchLifecycle->>Player: Notifies player match end has been processed

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, game flow 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 the entire game flow, and how to handle error cases in a communicative, player-friendly way.

Description #

Below is a simplified overview of how Pragma Engine facilitates game flows.

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.
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.
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.
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.
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).
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 Game Flow 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

Unreal	Unity	trigger
`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 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 OnPreferredGameServerZonesChanged`	`public 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`.
`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.
`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:

the game client running on the player’s machine
services within Pragma Engine
- Session service
- Party service
- Matchmaking service
- Match Lifecycle service
- Match Capacity service
the game server

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.

Service	Description
Party service	Allows players to group up and make pregame selections. These pregame selections may include settings such as difficulty, game mode, characters, or cosmetics.
Matchmaking service	Responsible for grouping parties together to form complete teams and matching teams against each other.
Session service	Tracks 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 service	The 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 service	Keeps 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 Game Flow Plugins #

Plugin	Description
PartyPlugin	Enables the customization of in-party behaviors.
GameServerCompatibilityPlugin	Determines whether a group of players can play a match together on a common `GameServerVersion`.
MatchmakingStrategy	Contains all matchmaking logic.
MatchEndPlugin	Enables the customization of match end player data update processing.
MatchFoundPlugin	Enables `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 game flow, 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.

Error Handling #

The internet was unfortunately not built to prioritize real-time multiplayer games. Players can have all sorts of issues due to their machine or internet connection, and even the most reliable datacenters can go offline. There are also error cases outside of network connectivity issues. Let’s take a look at how we handle some of these scenarios.

The game server never responds #

When a match is found, the Match Lifecycle service calls the Match Capacity service to find an available game server. If a game server isn’t found or never responds, the Match Lifecycle service releases all players after a configurable timeout. This way, players are able to re-enter matchmaking.

The match does not appear to end #

Pragma Engine will have a configurable maximum match duration. This prevents the engine from assuming that players are still in a match and therefore blocking them from playing another match.

Players disconnect from the game while it is still ongoing #

The Session service tracks each player’s state and is aware that the disconnected player was playing a game. When the player attempts to reconnect and if the match is still ongoing, the engine sends match details and connection information so that the player can rejoin their match.

Game server and game client version mismatch #

You can specify matching game server and client versions via the PartyService.gameServerCompatibilityPlugin. If players using an older game client version remain connected to the platform at the time you remove the matching game server from service, Pragma will remove and prevent them from re-entering matchmaking. We provide the OrderedGameServerCompatibilityPlugin as a sample implementation for how this functionality can be implemented.

Contents #

Topic	Description
Party	Allows players to create a party with their friends and configure their game before entering matchmaking.
Matchmaking	Connect parties to create matches. Utilitizes game mode and queue configuration, matchmaking rules, and matchmaking.
Session	Tracks the player's current status within Pragma Engine.
Game Server Management	Launch matches, manage player sessions, support reconnect, and process match end results.
Match End	Grant content, update quests and progression data, and grant rewards.