Set Up Persistent End Game via SQS #

Instead of sending EndGame requests directly to the Pragma backend via RPC, game servers can route these requests through Amazon SQS. This decouples the game server from the Pragma backend, allowing game servers to continue posting end-game data even when the platform is temporarily unavailable for maintenance.

When SQS passthrough is enabled, the SDK posts EndGame requests to an API Gateway that forwards them to an SQS queue. The Pragma backend reads from this queue and processes the requests asynchronously.

Step 1: Provision the SQS queue for your shard #

Contact your Pragma CSM to provision an SQS queue for your shard. After the infra is updated you will be able use the SQS in your shard.

Step 2: Configure the SqsReaderService #

Enable the SqsReaderService on the Pragma backend by adding the following to your YAML config.:

game:
  serviceConfigs:
    SqsReaderServiceConfig:
      enabled: true

Result: The Pragma backend reads and processes messages from the SQS queue.

Step 3: Enable processing of unknown game instances #

To support processing EndGame requests after a platform restart (when the game instance is no longer in memory), enable the processEndGameForUnknownInstance config:

game:
  serviceConfigs:
    GameInstanceServiceConfig:
      processEndGameForUnknownInstance: true

When enabled, Pragma creates a stub game instance for EndGame requests that reference a game instance not currently in the cache. This is required for the SQS flow because messages may arrive after the platform has restarted.

Result: EndGame requests for game instances not in memory are processed instead of rejected.

Step 4: Implement prepareUnknownInstanceForEndGameRequest on your GameInstancePlugin #

When processEndGameForUnknownInstance is enabled and an EndGame request arrives for a game instance not in the cache, the GameInstancePlugin.prepareUnknownInstanceForEndGameRequest method is called before handleBackendEndRequest:

suspend fun prepareUnknownInstanceForEndGameRequest(
    gameInstanceSnapshot: GameInstance.GameInstance,
    playerGameResults: List<PlayerGameResult>,
    requestExt: ExtEndGameRequest,
) {
}

This plugin method allows you to set up any state on the GameInstance that your handleBackendEndRequest needs. If you don’t do anything, then the handleBackendEndRequest will receive an empty GameInstance object.

Our recommendation is to Forward all required state from the game server — include all necessary data in the ExtEndGameRequest and playerGameResults and populate the GameInstance object in prepareUnknownInstanceForEndGameRequest.

Result: Unknown game instances are prepared with enough state to process end-game logic correctly.

Step 5: Enable SQS passthrough on the game server SDK #

Unreal #

Enable SQS passthrough in your Game.ini:

[/Script/PragmaSDK.PragmaSdkConfig]
bSqsPassthrough=true

When bSqsPassthrough is enabled and the SDK has received SQS connection info from the platform (via LinkV1 or CreateAndLinkV1), the SDK automatically routes MatchApi.EndGame() through SQS instead of making a direct RPC call.

If the SDK has bSqsPassthrough enabled but did not receive SQS connection info from the platform, it falls back to the normal direct RPC flow.

Result: Game servers post EndGame to SQS via API Gateway instead of calling the Pragma RPC directly.

Related pages #

• Persistent end game via SQS — architecture deep-dive covering error handling, retries, idempotency, and the Dead Letter Queue
• End game instances — reference for all ways to end a game instance