Ext Data Flows #

This section provides in-depth information on how multiplayer ext data moves through the multiplayer services.

Pragma allows developers to accept, transform, and forward custom data at multiple points in the multiplayer workflow. At each point, plugin methods can perform tasks such as data validation, cleaning, aggregation, and more.

In general, data is populated by one service or plugin, passed to another service, transformed and rebuild onto another ext, and again forwarded.

Player selection data #

The following examples describe how a player’s character selection data makes it’s way from the client or backend service to the game instance.

Scenario 1: Player joins a party and enters matchmaking

1. When players request to join a party, the client populates the ExtPlayerJoinRequest payload and passes it to the Party service.

2. The Party service can handle the request via the Party Plugin’s onAddPlayer() method and populate the ExtPartyPlayer payload.

3. When the party is ready to enter matchmaking, the party service builds the ExtMatchmakingPlayer proto for the Matchmaking service to use in the matchmaking logic.

4. When the Matchmaking service creates a new game instance, it passes individual player data to the Game Instance service on the player’s ExtBackendAddPlayer payload (PlayerToAdd.ext).

5. Finally, the Game Instance service can handle the ExtBackendAddPlayer data in the Game Instance Plugin’s handleBackendAddPlayersRequest() method and store the player data in the Game Instance and Game Player data stores.

   Note: The ExtBackendAddPlayerRequest ext passed to the handleBackendAddPlayersRequest() method contains general data about adding a player, not individual player data.

Scenario 2: Player joins an existing game instance directly

1. When players request to join a game instance, the client populates the ExtPlayerJoinGameInstanceRequest payload and passes it to the Game Instance service.
2. The Game Instance service can handle the ExtPlayerJoinGameInstanceRequest data in the Game Instance Plugin’s handlePlayerJoinRequest() method and store the player data in the Game Instance and Game Player data stores.

Scenario 3: A plugin method adds a player to an existing game instance

1. When a backend service requests to add a player to a game instance, it passes individual player data to the Game Instance service on the player’s ExtBackendAddPlayer payload (PlayerToAdd.ext).

2. The Game Instance service can handle the ExtBackendAddPlayer data in the Game Instance Plugin’s handleBackendAddPlayersRequest() method and store the player data in the Game Instance and Game Player data stores.

   Note: The ExtBackendAddPlayerRequest ext passed to the handleBackendAddPlayersRequest() method contains general data about adding a player, not individual player data.

Rich presence selections #

The following examples describe how a custom rich presence representing a player’s status is set and updated.

Scenario 1: Player requests to update their status

1. When a player requests to update their status, the client populates the ExtRichPresencePlayerRequest payload and passes it to the Presence service.
2. The Presence service handles the request via updateRichPresenceFromPlayer() and edits the ExtRichPresence.

Scenario 2: A plugin method requests a player status update

1. When a backend service requests an update to a player’s status, it passes presence data to the Presence service on the ExtRichPresenceBackendRequest payload.
2. The Presence service handles the request via updateRichPresenceFromBackend() and edits the ExtRichPresence.

Updated game data #

The following examples describe how player clients and backend services can update data about a game instance.

Scenario 1: Player requests to update game player connection details

1. When a player requests to update game data, such as their connection details, the client populates the ExtPlayerUpdateRequest payload and passes it to the Game Instance service.
2. The Game Instance service handles the request via handlePlayerUpdateRequest() and edits the ExtData.

Scenario 2: A plugin method or the game server requests to update game phase

1. When a backend service or game server requests to game data, such as a game phase, the backend or server populates the ExtBackendUpdateRequest payload and passes it to the Game Instance service.
2. The Game Instance service handles the request via handleBackendUpdateRequest() and edits the ExtData.

Game results #

The following example describe how game server can send a player their game results when a game instance ends.

1. When a game instance ends, the game server populates ExtPlayerGameResult, which can include information such as points earned.
2. The ExtPlayerGameResult is passed to the Game Instance service on the PlayerGameResult object.
3. The Game Instance service handles the request via the handleBackendEndRequest(), which can be used to perform calculations and populate the ExtGameEnded payload. For example, the points earned from the ExtPlayerGameResult can be used to calculate a rewards delta that is placed on ExtGameEnded.
4. The ExtGameEnded payload is sent to the player on the OnGameEnded notification.