Progression #

Progression systems are the beating heart of live-service games. Many games include multi-tiered progression, level-up, and rewards systems.

The Update system enables updating existing instanced items at various key moments, such as match end processing. By utilizing the Player Data service and instanced items, game teams receive the same engine capabilities of storing, retrieving, caching, and processing progression data.

Two types of progression data are returned from the match end event:

match metrics: A one-time event for the match sent to the metrics collector (unlike stats, which are stored and retrieved per player). Used to create dashboards and other live service reports.
player stats: Any numerical statistic coming from the match stored per player. Includes content like damage dealt, steps taken, shots fired, etc. Stored as a key-value pair mapping a string to an int64.

Quick Guides #

Granting stats and items on match end #

On match end, a partner call MatchEndV3 handles progression data. A WebSocket message is sent to all players in a match.

playerMatchEnds holds content for each player, including stats and any items won during the match.

{
  "requestId": 1,
  "type": "MatchLifecycleRpc.MatchEndV3Request",
  "payload": {
    "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c3",
    "matchEnd": {
      "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c3",
      "playerMatchEnds": [
        {
          "playerId": "<PragmaPlayer01Id>",
          "stats": {
            "shotsFired": 3000,
            "kills": 12
            },
          "serverItemUpdates":  [{"stackable": {"catalogId": "XP", "amountChanged": 10000}}],
          "itemGrants": [{"instanced": {"catalogId":"fireDragon"}}, {"stackable": {"catalogId": "gold_coins", "amount":"2"}}],
          "rewardGrants": [{"tableId": "pet-update-rewards", "count": 1}]
        },
        {
          "playerId": "<PragmaPlayer02Id>",
          "stats": {
            "shotsFired": 2134,
            "kills": 5
          }
        },
        {
          "playerId":"<PragmaPlayer03Id>" ,
          "stats": {
            "shotsFired": 124
          }
        },
        {
          "playerId": "<PragmaPlayer04Id>",
          "stats": {
            "shotsFired": 12
          }
        }
      ]
    },
    "matchMetrics": [
      {
        "name": "myLittleMetric",
        "value": 26
      },
      {
        "name": "myBigMetric",
        "value": 2600
      }
    ]
  }
}

When the match is complete, each player receives a message with any rewarded items and their stats. This example MatchProcessedV3Notification is for the winner of the example game, with their extra rewarded items:

{"matchId":"51a7f830-e84c-46a8-ad14-d83d99d045c3",
	"pragmaMatchProcessed":{"full":{"stackables":[
		{"catalogId":"gold_coins","instanceId":"94928d9f-b80d-4e3e-acaf-7370ddcbadc6","amount":"36"},
		{"catalogId":"XP","instanceId":"5396cb94-67a7-470f-9554-afa36e170134","amount":"10000"}],
	"instanced":[{"catalogId":"fireDragon","instanceId":"46b475bc-a250-4791-bc62-599d9c31357a","ext":{"reserved":1,"exampleString":"","exampleLong":"0","exampleProto":"00000000-0000-0000-0000-000000000000","pet":{"bonus":"LUCK_BONUS","bonusAmount":"5","xp":"0"}}}],"version":"1"},
	"inventorySummaries":[
		{"stackables":[{"catalogId":"gold_coins","tags":[],"amountChanged":"2"},{"catalogId":"XP","tags":[],"amountChanged":"10000"},{"catalogId":"gold_coins","tags":[],"amountChanged":"34"}],
		"instanced":[{"catalogId":"fireDragon","tags":[],"operation":"ADDED","final":{"catalogId":"fireDragon","instanceId":"46b475bc-a250-4791-bc62-599d9c31357a","ext":{"reserved":1,"exampleString":"","exampleLong":"0","exampleProto":"00000000-0000-0000-0000-000000000000","pet":{"bonus":"LUCK_BONUS","bonusAmount":"5","xp":"0"}}}}]}],
	"progressionMatchProcessed":{"stats":{"shotsFired":"3000","kills":"12"}}}}.

Checking player progression by getting player stats #

Players are sent stats from a match using matchEndV3. However, if you’d like to view these stats as operator, use the GetPlayerStats call:

{
  "requestId": 1,
  "type": "PlayerProgressionRpc.GetPlayerStatsV1Request",
  "payload": {
      "playerId": "<PragmaPlayer01Id>"
  }
}

The stats for player 1 are included in the response:

{
  "sequenceNumber": 0,
  "response": {
    "requestId": 1,
    "type": "PlayerProgressionRpc.GetPlayerStatsV1Response",
    "payload": {
      "values": {
        "kills": "12",
        "shotsFired": "3000"
      },
      "notFoundFieldName": []
    }
  }
}