Battle Pass #

A battle pass is a typical approach for delivering content to players by combining monetization and engagement. Players earn battle pass XP by playing games and completing quests, and unlock rewards upon leveling up their battle pass. Battle passes are oftentimes associated with some kind of seasonal schedule or content.

Quick Guides #

Implementing a battle pass #

This is a sample battle pass implementation defined with extension data. All of these are supported within Pragma using extension data and plugin code.

Protos #

  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryContentExt.proto.
  2. Add BattlePassSpec as a oneof to the ExtInstancedSpec message. Your ExtInstancedSpec will look something like this:
message ExtInstancedSpec {
  string name = 1;
  oneof data {  
   BattlePassSpec battle_pass_spec = 2;
  }
}
  1. Create a Levels message that defines the attributes of a level:
message Levels {
  int64 level = 1;
  int64 required_xp = 2;
  repeated string rewards_free = 3;
  repeated string rewards_premium = 4;
}
  1. Create a BattlePassSpec message that contains levels:
message BattlePassSpec {
  repeated Levels levels = 1;
}
  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryExt.proto.
  2. Since we will use Levels defined in inventoryContentExt.proto, add the following import:
import "shared/inventoryContentExt.proto";
  1. Modify the ExtInstancedItem message by adding BattlePassData to the oneof.
message ExtInstancedItem  {
  oneof data {
    BattlePassData battlePass = 5;
  }
}
  1. Define the BattlePassData message:
message BattlePassData {
  string currentBattlePass = 1;
  int64 xp = 2;
  Levels currentLevel = 3;
  bool IsPremium = 4;
  int64 LevelNumber = 5;
}
  1. Open 5-ext/ext-protos/src/main/proto/shared/inventoryRpcExt.proto.
  2. Modify the ExtInstancedItemServerUpdate message by adding BattlePassUpdate to the oneof.
message ExtInstancedItemServerUpdate {
  oneof data {
    BattlePassUpdate battle_pass_update = 2;
  }
}
  1. Define the BattlePassUpdate message:
message BattlePassUpdate {
  int64 xp = 1;
}

JSON #

{
  "catalogId": "battle-pass-1",
  "name": "Battle Pass Season 1",
  "tags": [
    "battlepass",
    "season1"
  ],
  "ext": {
    "battlePassSpec": {
      "levels": [
        {
          "level": 1,
          "requiredXp": 1000,
          "rewards-free": [
            "Bp-1-lvl-1-rewards-free",  // level 1 free rewards
            "Bp-1-rewards-free"         // reusable free pack
          ],
          "rewards-premium": [
            "Bp-1-lvl-1-rewards-prem"   // level 1 premium rewards
          ]
        },
        {
          "level": 2,
          "requiredXp": 2000,
          "rewards-free": [            // no free rewards for level 2
          ],
          "rewards-premium": [
            "bp-1-lvl-2-rewards-prem"
          ]
        }
      ]
    }
  }
}

Tracking a player’s progress #

The following code is a battle pass progress item that tracks a player’s progress throughout the season.

{
  "currentBattlePass": "battle-pass-1",
  "xp": 1370,
  "currentLevel": 1
}

Tracking XP and granting rewards #

The Update system is used to process match end events, track XP balance, and grant rewards when players level up their pass.

fun updateBattlePass(
    initialItem: InstancedItem,
    battlePassProgress: BattlePassProgress,
    battlePassSpec: BattlePassSpec
): UpdateResult {

    val rewards: MutableList<RewardGrant> = mutableListOf()
    val updatedItem = battlePassProgress.toBuilder()

    updatedItem.xp += matchEnd.battlePassXp

    val nextLevel = max(battlePassProgress.currentLevel + 1, battlePassSpec.levels.size - 1)

    val nextBattlePassLevel = battlePassSpec.levels[nextLevel]
    if (updatedItem.xp > nextBattlePassLevel.requiredXp) {
       updatedItem.currentLevel += 1
       rewards.addAll(nextBattlePassLevel.rewards)
    }

    return UpdateResult(updatedItem.build(), rewards)
}
Overview
Currencies