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.
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
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
playerLeaveV1. Provide the match ID, the match end payload, and the list of metrics to record about the match.
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.
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
keepAliveIntervalMillis configuration for development in
dev-defaults.yml is instead set to
5000 milliseconds (5 seconds). To modify these values, edit the
To disable this feature, set the
MatchLifecycleServiceConfig.enableKeepAlive configuration property to
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
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
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.