Search Unity

Try out our battle pass sample using Unity Gaming Services Use Cases

April 22, 2022 in Games | 11 min. read
Battle Pass Sample Header
Battle Pass Sample Header

Is this article helpful for you?

Thank you for your feedback!

The Unity Gaming Services (UGS) Use Cases are a collection of samples designed to show you how you can use multiple UGS products to solve common game development challenges. 

These samples implement typical backend game use cases and game design elements, show how to resolve specific development tasks, and highlight the efficiency you can achieve in your game backend by integrating different UGS packages in your project.

One of these samples is a battle pass — a seasonal reward tier system with a free track and a premium track. This article will explain how this sample works, and how you can implement it in your own game. 

What are UGS Use Cases?

This is an ongoing Unity project that you can download and run in the Unity Editor. You can then look at the code to see how various use cases can be addressed by using Unity Gaming Services.

The main goal of this project is to help developers get through the ramp-up process faster by having access to working examples. The code is designed to be easy to read and accessible to developers of all levels of experience.

What is a battle pass?

A battle pass is a popular way to retain players by offering rewards for playing the game, with an additional premium layer to help your game generate revenue in the long term.

This is how it generally breaks down:

  • As a player progresses in your game, they earn points which unlock increasingly valuable reward tiers.
  • There are two parallel reward tracks:
    • Free rewards that can be claimed by all players.
    • Premium rewards that are unlocked by purchasing a battle pass, often with premium in-game currency.
  • The reward tracks are only available for a limited time, usually for the length of a game “season”.
Battle Pass screen

How does the sample work?

For live games, especially multiplayer ones, the server should be the source of truth for most of the players’ data. 

This prevents cheating tactics which may allow a player to have an advantage over another, or grant a player items or currencies that would otherwise need to be purchased or earned. 

Similarly, in order for seasonal rewards or battle passes to be fair for all players, all data and decisions need to be managed server-side. 

In the design of this battle pass sample, Cloud Code (beta) service does most of the heavy lifting in terms of handling the backend infrastructure. Cloud Code allows you to write and run your game logic away from the client.

Other tools used in this sample include Cloud Save (beta), which allows you to store player data to the cloud. In this case, it allows the player’s season progress to be stored in a flat key-value system. A battle pass ownership flag for the current season is also stored with Cloud Save.

Game Overrides (powered by Remote Config), which lets you create personalized in-game player experiences to determine the content of the current season and battle pass tiers.

All of the tier rewards in the battle pass are either currencies or inventory items, which are all managed through Economy (beta). There is also one Purchase set up in Economy for exchanging gems for a battle pass.

As with any game where player data is managed by an online back-end, each player will need to sign in to the game. For this, we're using Authentication (beta). Once the user is signed in, all Unity Gaming Services SDKs will automatically know to send the player's unique ID with every server request.

Here’s how the sample works: 

  • Seasonal reward configuration data is sent from Game Overrides to the client, and is also available in Cloud Code (read only). The game client will use this data to determine the UI. Cloud Code will use this data to determine which rewards to grant a player that claims a valid reward tier.
  • Cloud Save is used to track the player’s progress through the reward tiers. The player will have an array of mutually exclusive tier states with three possible values: Locked, Unlocked, or Claimed.
  • Cloud Save also stores a value indicating whether the player has purchased the battle pass for the current season.
Battle Pass blog diagram

Player state can be obtained and set directly from the client by using Cloud Save, but that shouldn’t be done in this case.

Setting the Cloud Save data directly would make the player data client-authoritative instead of server-authoritative, which opens the door to hacks. By using Cloud Code, we can validate the changes before writing the data to Cloud Save.

Reading the player state directly from Cloud Save could result in getting data from the previous season that has ended. By using Cloud Code, we can automatically reset the player's season state if the season has ended.

How to add a battle pass to your game

By using this sample package, you can implement a fully functional, server-authoritative battle pass with Unity Gaming Services.

Seasonal rewards with Game Overrides

Game override

Within the Unity Dashboard, you can define your game’s battle pass configuration for a given period of time by setting up a Game Overrides campaign and populating it with JSON values. 

A campaign can be for any time span, whether you want to run a special event for an hour, a weekend, or in the case of a Battle Pass, a season lasting months.

Server-authoritative logic with Cloud Code

The player’s interactions with the game’s UI will send Cloud Code requests to:

  • Gain Season XP

  • Claim a reward

  • Purchase a battle pass

  • Record the player’s season progress

  • Return the progress data to the game client

Some of these calls could be done more simply by making direct calls to Economy or Cloud Code. However, with all of these types of requests, you may need to also reinitialize the player’s season progress if the season has changed or if they’re new to the system. 

You don’t want the client to decide whether the season data needs to be reinitialized before making each request.

In this battle pass sample’s design, the player’s past rewards are automatically granted if they upgrade to the battle pass (after already claiming free rewards). Because of this, the only way to process a battle pass purchase is via a Cloud Code function. 

The function makes the call to Economy to complete a purchase with a cost but no rewards. If that is successful, two things happen:

  • The battle pass is granted to the player in the form of a value stored in Cloud Save,  which only represents the battle pass for the current season.

  • The player is granted any battle pass rewards for tiers they’ve already claimed.

More possibilities with battle passes

There are many possible designs for seasonal rewards and battle passes — Unity Gaming Services won’t limit you to this example.

  • The arrangement of tiers is up to you. Maybe some tiers don’t contain free rewards. Maybe, rather than a linear track, you prefer a more complex system where players can choose from a page filled with tiers, in any order, to eventually unlock the next page. Virtually any level of battle pass design complexity is possible. 
  • This sample uses currencies for most of the rewards, but most common battle pass rewards in multiplayer games are cosmetic items. Your battle pass’s design can depend on whether your game is single player or multiplayer.

You could use the Unity In-app Purchase package to charge real money for your battle pass instead of in-game currency.

Unity Gaming Services Use Cases

The Unity Gaming Services Use Cases collection includes several other sample packages apart from the battle pass:

  • Loot boxes: Reward players with a random Economy currency using Cloud Code to perform the Economy grants.
  • Daily rewards: Grant players random collections of both currencies and inventory items at timed intervals.
  • Starter Pack: Allow players to purchase a Starter Pack using Cloud Code to implement the one-time-only purchase.
  • Seasonal events: Update game content remotely based on timed special events.
  • A/B testing for level difficulty: Segment players into multiple test groups in order to determine which variation of a specific variable is the most engaging to the players (in this case, the amount of XP required for leveling up).
  • Idle clicker mini-game: Update server authoritative game state in real-time, similar to idle clicker games.
  • Cloud AI mini-game: Server authoritative gameplay in a simple Tic-Tac-Toe game played against AI running on UGS with persistent state, currency rewards, stats, and straightforward AI.
  • Command batching: Group game commands into a queue and process them on the server in a single batch to reduce the volume and frequency of server calls made during gameplay.

Make sure to check back in the GitHub repository as this project will continue to grow to include more use cases for Unity Gaming Services.

April 22, 2022 in Games | 11 min. read

Is this article helpful for you?

Thank you for your feedback!