Match End #

The Match End event provides a rich set of capabilities that integrate with the Player Data service to grant content, update quests and progression data, and grant rewards. The results are aggregated and sent to players as a single payload to simplify the client match details and “play again” workflows.

sequenceDiagram participant gs as Game Server participant ml as Match Lifecycle participant pd as Player Data participant i as Custom Service participant p as Player gs->>ml:matchEnd(details) note right of ml: Send to multiple services par In Parallel ml->>+pd:matchEnd(details) pd->>-ml:results ml->>+i:matchEnd(details) i->>-ml:results end note right of ml: Send combined results to players ml->>p:matchResults(results)

Play Again #

Pragma Engine persists parties and their configurations between matches to create seamless transitions through multiple game loops. Upon a Match End, all players are returned to their original party, allowing them to quickly prepare for the next match and queue again.

Match End Cases #

When a match ends, Pragma Engine expects a match end request from the game server.

The game server can remove individual players from the match via a PlayerLeave request. All players in that PlayerLeave request have their individual match end data processed, and receive a MatchProcessed notification when the match eventually ends. The list of match end processing jobs to run is gathered from MatchEndPlugin.getMatchEndJobs.

If a match end request is successfully sent and received, this is considered a successful match end. Pragma Engine also provides functionality for handling when a match end is not successful. In both cases, notifications with relevant information are sent from the engine to player clients.

Match End must be invoked to end the match, even if all players have left the match via PlayerLeave requests.

Example: Processing match ends for a subset of players without ending the match

While many games end for all players at once, some game designs lead to the game ending for players at different times, such as the RTS or Battle Royale genres. Even if a game hasn’t ended, you may wish to process match end stats for the leaving players immediately after those players leave by having the game server call playerLeaveV1. Provide the match ID, the match end payload, and the list of metrics to record about the match.

Successes #

After a successful match end, Pragma Engine sends players a MatchProcessedV3Notification. This notification indicates that match end information has been successfully processed, and the match has ended.

Failures #

Pragma Engine provides two optional features to account for situations where the match end request never arrives: Keep Alive Heartbeats and Absolute Timeouts. A match end payload can fail to arrive due to game server crashes, game code bugs, network issues, or malicious actors. These features help release players from a match and allow them to reenter the game loop to start a new match.

In these failure situations, Pragma Engine sends a MatchTerminatedV1Notification to players, including a reason for shutdown.

When the game is forced to shut down, no match end data is processed.

Keep Alive Heartbeats #

The Keep Alive Heartbeats feature requires game servers to send occasional heartbeats after starting a match. This allows Pragma Engine to confirm that the match and game server are still operational.

When enabled, Pragma Engine expects a MatchKeepAliveV1 request based on the configured amount of time (keepAliveIntervalMillis). If the engine doesn’t receive the request after a consecutive set of the configured amount of missed values (keepAliveMissesLimit), it ends the match and returns players to their party, calling the PartyPlugin.returnFromMatch plugin method.

Game servers using the Pragma Engine-provided Unreal and Unity SDKs automatically send heartbeats to Pragma Engine on a successful response of the MatchLifecycleService.MatchReady method when this feature is enabled. It does this by starting a background process that makes the necessary MatchKeepAliveV1 requests every keepAliveIntervalMillis while the match is progress.

The configuration for this feature can be found in MatchLifecycleServiceConfig. This feature is enabled by default, with a 30000 milliseconds (30 seconds) value for keepAliveIntervalMillis in production environments, and a keepAliveMissesLimit value of 3.

A separate keepAliveIntervalMillis configuration for development in dev-defaults.yml is instead set to 5000 milliseconds (5 seconds). To modify these values, edit the local-dev.yml file.

To disable this feature, set the MatchLifecycleServiceConfig.enableKeepAlive configuration property to false.

As a best practice, we recommend against turning off the Keep Alive Heartbeats feature, as it’s critical for game flow health.

Absolute Timeouts #

The Absolute Timeouts feature makes Pragma Engine end a match after a specified period of time elapses.

To enable this feature, set the MatchLifecycleServiceConfig.enableMatchAbsoluteTimeout configuration property to true and provide a value for MatchLifecycleServiceConfig.matchAbsoluteTimeoutMillis.

Once enabled, Pragma Engine starts a background tasks that runs after a configured amount of time (matchAbsoluteTimeoutMillis) passes. If a match is still in progress when the background task runs, the engine ends the match and returns players to their party, calling the PartyPlugin.returnFromMatch plugin method.

Content Grants #

Match end has built-in support for:

item grants
item and progression updates
rewards grants
metrics

These capabilities can be extended further with the standard plugin + extension data approach.

Match End Event Registration #

Relevant services can register themselves to receive the Match End event. The Match Lifecycle service aggregates the results from all service updates and send a single result payload to players. This keeps client processing simple and prevents typical client bugs associated with coordinating multiple async notifications while the client is transitioning out of a match and rendering match results.