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 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.
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 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.
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 Multiplayer 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 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 #
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. Utilizes game mode and queue configuration, matchmaking rules, and matchmaking. |
Session | Tracks the player's current status within Pragma Engine. |
Match Lifecycle | Track in-progress matches, receive match events from the game server, and execute all match end processing. |
Match Capacity | Process match requests and coordinate with a game server management provider to allocate game servers. |
Match End | Grant content, update quests and progression data, and grant rewards. |
Error Handling | Common errors for Multiplayer services. |