Using the Match End Services #

Let’s take a look at a few match end service examples: granting inventory, sending player statistics, and sending metrics.

For demonstration purposes, we’ll be manually simulating service calls with Postman. In a real world scenario, different service calls come from various sources, such as game clients and game servers.


Grant inventory #

A convenient way to grant player inventory is via the game loop, where the game server reports inventory updates to the platform at the end of a match.

The Inventory service processes the match end payload, resulting in updated inventory for each player. In a real world scenario, the platform then sends the updates, including inventory updates, to logged in players. In this example, we’ll have to manually retrieve the player inventory to confirm the inventory updates.

  1. Run make run to start Pragma Engine. Run this in a terminal with platform as the working directory.
  • Alternatively, Pragma Engine can be run from IntelliJ. From the IntelliJ toolbar in the upper right, ensure MainKt - LocalConfigured is selected, then click the play button.
  • If not, click Add Configuration…. In the Run/Debug Configurations window that appears, expand Kotlin in the left hand side, then select MainKt - LocalConfigured. Click OK. Click the play button in the IntelliJ toolbar to start Pragma Engine.
  • Once the engine has started successfully, it prints the message [main] INFO main - Pragma server startup complete.
  1. Get a pragmaPlayerId by opening Postman and sending PragmaDev ➨ Social ➨ Player ➨ Account ➨ authenticateOrCreateV2.
  2. Save the pragmaPlayerId for use in the following examples.
  3. Send PragmaDev ➨ Game ➨ RPC - Player ➨ Inventory ➨ storePurchaseV4 with the following request body to get coins from the store:
{
  "requestId": 1,
  "type": "InventoryRpc.StorePurchaseV4Request",
  "payload": {
    "data" : {
      "ext": {},
      "storeId": "freeVendor",
      "storeEntryId": "starterBundle",
      "amount": 1
    }
  }
}
  1. Confirm you’ve received 1000 coins and 100 diamonds. Save the instanceId for coins for later use.

  2. Send PragmaDev ➨ Game ➨ RPC - Partner ➨ MatchManagement ➨ MatchEndV3 with the following request body. Be sure to replace the playerId and instanceId fields with the appropriate ids from previous steps. In a production scenario, the game server would make the MatchEndV3 service call.

{
  "requestId": 1,
  "type": "MatchLifecycleRpc.MatchEndV2Request",
  "payload": {
    "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c1",
    "matchEnd": {
      "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c1",
      "playerMatchEnds": [
        {
          "playerId": "<<YOUR PLAYER ID>>",
          "serverItemUpdates":  [
            {
              "stackable": {
                "catalogId": "coins",
                "instanceId": "<<YOUR INSTANCE ID>>",
                "amountChanged": 500
              }
            }
          ],
          "itemGrants": [{"instanced": {"catalogId": "laserSword"}}]
        }
      ]
    }
  }
}
  1. Send PragmaDev ➨ Game ➨ RPC - Player ➨ Inventory ➨ getInventoryV2. No changes to the request body are required. Confirm that the player inventory contains 1500 coins (1000 from store purchase and 500 from match end) and a laserSword.

Send player statistics #

Player stats are any numerical statistic coming from the match and are stored on a per-player basis. Stats might include damage dealt, steps taken, shots fired, or number of times fallen off a skateboard.

  1. Run make run to start Pragma Engine. Run this in a terminal with platform as the working directory.
  • Alternatively, Pragma Engine can be run from IntelliJ. From the IntelliJ toolbar in the upper right, ensure MainKt - LocalConfigured is selected, then click the play button.
  • If not, click Add Configuration…. In the Run/Debug Configurations window that appears, expand Kotlin in the left hand side, then select MainKt - LocalConfigured. Click OK. Click the play button in the IntelliJ toolbar to start Pragma Engine.
  • Once the engine has started successfully, it prints the message [main] INFO main - Pragma server startup complete.
If necessary, get a pragmaPlayerId by opening Postman and sending PragmaDev ➨ Social ➨ Player ➨ Account ➨ authenticateOrCreateV2. Save the pragmaPlayerId for use in the following examples.
  1. Send PragmaDev ➨ Game ➨ RPC - Partner ➨ MatchManagement ➨ MatchEndV3 with the following request body to get coins from the store:
{
  "requestId": 1,
  "type": "MatchLifecycleRpc.MatchEndV2Request",
  "payload": {
    "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c2",
    "matchEnd": {
      "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045c2",
      "playerMatchEnds": [
        {
          "playerId": "<<YOUR PLAYER ID>>",
          "stats": {
            "damageDealt": 250,
            "stepsTaken": 100,
            "shotsFired": 25
          }
        }
      ]
    }
  }
}

This request simulates the end of a match and sends the following stats to be logged: 250 damageDealt, 100 stepsTaken, and 25 shotsFired.

  1. Run PragmaDev ➨ Game ➨ RPC - Operator ➨ PlayerProgression ➨ GetPlayerProgressionDataForOperatorV1 with the appropriate playerId in the request body to see aggregated stats. Confirm that the player has received their new stats.

  2. Prepare to send another MatchEndV3 request by making the following modifications:

    • Modify the damageDealt, stepsTaken, and shotsFired fields, and create some brand new stats fields of your own.
    • Modify the matchId field, as matchIds are unique and can only be used once.
  3. Send MatchEndV3 again.

  4. Resend MatchEndV3. Note that the values of damageDealt, stepsTaken, and shotsFired have updated values. Additionally, your newly-created stats should also appear.

Send match end metrics #

While stats are stored and retrieved per player, metrics are a one-time event for the match and are sent to a metrics collector. These can’t be retrieved from the platform, and are instead used to create dashboards and similar live service reports. To verify that match metrics are being recorded, some setup work is required.

Enable metrics in the config file #

  1. Edit LocalConfig.yml by adding the following lines:
game:
  pluginConfigs:
    MetricsNodeService.prometheusGatewayModuleProvider:
      class: "pragma.metrics.PrometheusGatewayModuleProvider"
  1. Run make run to start Pragma Engine. Run this in a terminal with platform as the working directory.
  • Alternatively, Pragma Engine can be run from IntelliJ. From the IntelliJ toolbar in the upper right, ensure MainKt - LocalConfigured is selected, then click the play button.
  • If not, click Add Configuration…. In the Run/Debug Configurations window that appears, expand Kotlin in the left hand side, then select MainKt - LocalConfigured. Click OK. Click the play button in the IntelliJ toolbar to start Pragma Engine.
  • Once the engine has started successfully, it prints the message [main] INFO main - Pragma server startup complete.

Send coins on match end #

  1. Send PragmaDev ➨ Game ➨ RPC - Partner ➨ MatchManagement ➨ MatchEndV3 with the following request body to track the match duration and number of players:
{
  "requestId": 1,
  "type": "MatchLifecycleRpc.MatchEndV2Request",
  "payload": {
    "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045d9",
    "matchEnd": {
      "matchId" : "51a7f830-e84c-46a8-ad14-d83d99d045d9",
      "playerMatchEnds": [
        {
          "playerId": "<<YOUR PLAYER ID>>"
        }
      ]
    },
    "matchMetrics": [
      {
        "name": "matchDurationInSeconds",
        "value": 12345
      },
      {
        "name": "numPlayers",
        "value": 1
      }
    ]
  }
}
  1. In a browser, navigate to http://localhost:10200/metrics and search for matchEnd. You should see entries for matchDurationInSeconds and numPlayers, confirming that metrics are being recorded.