Command Batching

Batch commands for server-side processing to optimize network efficiency, reduce overhead, and improve performance.

Read time 5 minutes

Last updated 4 days ago

Command batching is the concept where each game action is a Command which can be collected into a queue to be sent to the server in batches for processing. Command batching optimizes your game’s bandwidth to be as energy efficient as possible, and prevent poor performance due to frequent server calls or rate limiting. This provides a smoother game experience with less downtime.

In this sample, the player has a fixed number of turns. Each simulated action generates a command that is cached, then executed by the server as part of a batch at the end of the game, thereby reducing the number of calls to the server. For example, consider a game that distributes rewards after every action by calling Cloud Save to distribute player XP and Economy to distribute Coins. The player completes the following three actions:

The first action results in 100 XP and 10 Coins.
The second action results in 50 XP and 5 Coins.
The third action results in 200 XP and 30 Coins.

These three actions would result in a minimum of six calls to various Unity Services (in this case, Cloud Save and Economy). However, if all three of these actions are stored as batch commands and processed a single time, the game would only make two Unity Services calls: one to Cloud Save to increase XP by 350, and one to Economy to add 45 Coins.

Prerequisites

To use this sample use case, you must download and install the UGS Use Cases project in your Unity project.

Overview

To see this use case in action, open the samples menu and navigate to Command Batching. To open this scene directly and interact with the use case:

In the Unity Editor Project window, select Assets > Use Case Samples > Command Batching, then double-click
```
CommandBatchingSample.unity
```
to open the sample scene.
Press Play to enter Play mode.

Initialization

The

CommandBatchingSceneManager.cs

script performs the following initialization tasks in its

Start

function:

Initializes Unity Gaming Services.
Signs in the player anonymously using the Authentication service. If you’ve previously initialized any of the other sample scenes, Authentication will use your cached Player ID instead of creating a new one.
Retrieves and updates the player's currency balances from the Economy service.
Initializes the game interface and buttons.

Functionality

Player turns

In this sample, a single "game" involves making a fixed number of turns, where a single turn is completed by clicking on one of four buttons. Each button represents a simulated action with corresponding rewards. When you click on one of the action buttons, the following occurs:

The button’s
```
OnClick
```
method calls the
```
CommandBatchingSceneManager.cs
```
script, which consumes a turn.
The script then generates a command associated with the action you clicked and sends it to the batch queue for future server processing. Each command uses Remote Config values to map rewards for the corresponding action.
It also calls that action’s associated
```
CommandSystem
```
script to distribute rewards to the client.
Note: Local reward distribution allows players to immediately see the results of the turn, but is not server-authoritative. The server overwrites any local distributions after it validates and processes all commands at the end of the game.
Finally, the calling script checks to see if the player is out of turns, in which case it triggers the game-over condition.

Gave over

When the player has zero turns remaining, the game is over. The following occurs:

The client adds a final game over command to the batch queue.
The client sends the entire command queue to Cloud Code as a single JSON.
The
```
CommandBatch_ProcessBatch.js
```
Cloud Code script unpacks the JSON blob into a list of commands again, then verifies that the batch contains the exact number of expected commands in a valid order (for example, the player cannot trigger the Achieve Bonus Goal command until the Open Chest command occurs).
If the batch is valid, the Cloud Code script retrieves the rewards to distribute from Remote Config values then issues them directly through the Economy (currencies) and Cloud Save (XP and
```
GoalsAchieved
```
) services. If the batch is invalid, the script returns an error and rewards will not be distributed on the server.

Mapping the rewards in Remote Config allows you to tune them remotely in a single place, affecting both the client-side and server-side distributions simultaneously. The rewards for all commands in the batch are grouped by type, so if multiple commands increase XP, the total XP gains are added up and updated with a single server call to Cloud Save. Whether or not the Cloud Code script returns success or failure, the client code calls the Unity Services to retrieve their latest data. If the batch was processed successfully by the server, this should result in no visible change to the player's Currency,

GoalsAchieved

, or XP HUDs, because from their perspective the rewards were distributed immediately during game play. However, if the Cloud Code script failed to process an invalid batch, the client updates the player's status back to what it was before the game was played, overwriting the local state.

Note

This creates a mixed-authoritative game. At certain times, the game relies on the local (client) authority to know the player's stats and currency balances. However, the server ultimately has final authority on the player's state. While this mixed-authority setup is not appropriate for all game styles, it can be very useful for others, such as turn-based, single-player, infinite runner, and puzzle games. Command batching can also be a good starting point when developing a solution for offline support or bad connection tolerance in games that choose to provide such features.

Setup

Requirements

To replicate this use case, you'll need the following Unity packages in your project:

Package	Role
Authentication	Automatically signs in the player as an anonymous user to keep track of their data server-side.
Cloud Code	Processes queued commands at the end of a game.
Cloud Save	Stores the mapping between commands and their corresponding rewards, which the client and Cloud Code references to distribute rewards.
Deployment	Provides a cohesive interface to deploy assets for Cloud Services.
Economy	Retrieves the player's starting and updated currency balances at runtime.
Remote Config	Maintains key-value stores for player stats, such as XP and Goals Achieved.

To use these services in your game, activate each service for your Organization and project in the Unity Dashboard.

Unity Cloud services configuration

To replicate this sample scene's setup in your own Unity project, configure the following items:

Cloud Code scripts
Economy items
Remote Config values

To configure these items you can use the Deployment package, or manually enter them using the Unity Dashboard. The recommended best practice is to use the Deployment package as it greatly accelerates this process.

Using the Deployment package

To deploy configurations using the Deployment package:

Open the Deployment window.
Check in
```
Common
```
and
```
Command Batching
```
.
Click
```
Deploy Selection
```
.

This deploys all the necessary items.

Using the Unity Dashboard

You can use the Unity Dashboard to manually configure your services by project and environment. Refer to the following sections to configure this sample.

Cloud Code

Publish the following script in the Unity Dashboard:

Script	Parameters	Description	Location in project
`GrantEventReward`	`batch` An array of command keys. For example: {"commands": ["COMMANDBATCH_DEFEAT_RED_ENEMY","COMMANDBATCH_OPEN_CHEST","COMMANDBATCH_ACHIEVE_BONUS_GOAL","COMMANDBATCH_DEFEAT_BLUE_ENEMY","COMMANDBATCH_OPEN_CHEST","COMMANDBATCH_ACHIEVE_BONUS_GOAL","COMMANDBATCH_GAME_OVER"]}	Processes queued commands at the end of a game.	`Assets/Use Case Samples/Command Batching/Cloud Code/CommandBatch_ProcessBatch.js`

Script

Parameters

Description

Location in project

GrantEventReward

batch

An array of command keys. For example:


{"commands": ["COMMANDBATCH_DEFEAT_RED_ENEMY","COMMANDBATCH_OPEN_CHEST","COMMANDBATCH_ACHIEVE_BONUS_GOAL","COMMANDBATCH_DEFEAT_BLUE_ENEMY","COMMANDBATCH_OPEN_CHEST","COMMANDBATCH_ACHIEVE_BONUS_GOAL","COMMANDBATCH_GAME_OVER"]}

Processes queued commands at the end of a game.

Assets/Use Case Samples/Command Batching/Cloud Code/CommandBatch_ProcessBatch.js

Note

The Cloud Code scripts included in the

Cloud Code

folder are local copies because you cannot view the sample project's dashboard. Changes to these scripts do not affect the behavior of this sample because they are not automatically uploaded to the Cloud Code service.

Economy

Configure the following resources in the Unity Dashboard:

Resource type	Resource name	ID	Description
Currency	Coin	`COIN`	A reward for certain actions.
Currency	Gem	`GEM`	A reward for certain actions.

Remote Config

Set up the following config values in the Unity Dashboard:

Key	Type	Description	Value
`COMMANDBATCH_ACHIEVE_BONUS_GOAL`	JSON	Maps the `Achieve Bonus Goal` command to its corresponding rewards.	{"rewards":[{"service": "cloudSave","id": "COMMANDBATCH_XP","amount": 150},{"service": "cloudSave","id": “COMMANDBATCH_GOALSACHIEVED","amount": 1}]}
`COMMANDBATCH_DEFEAT_BLUE_ENEMY`	JSON	Maps the `Defeat Blue Enemy` button action to its corresponding rewards.	{"rewards":[{"service": "cloudSave","id": "COMMANDBATCH_XP","amount": 50},{"service": "currency","id": “GEM","amount": 5}]}
`COMMANDBATCH_DEFEAT_RED_ENEMY`	JSON	Maps the `Defeat Red Enemy` button action to its corresponding rewards.	{"rewards":[{"service": "cloudSave","id": "COMMANDBATCH_XP","amount": 50},{"service": "currency","id": “COIN","amount": 5}]}
`COMMANDBATCH_OPEN_CHEST`	JSON	Maps the `Open Chest` button action to its corresponding rewards.	{"rewards":[{"service": "cloudSave","id": "COMMANDBATCH_XP","amount": 100},{"service": "currency","id": “COIN","amount": 25},{"service": "currency","id": “GEM","amount": 25}]}
`COMMANDBATCH_GAME_OVER`	JSON	Maps the game over command (no more turns remain) to its corresponding rewards.	{"rewards":[{"service": "cloudSave","id": "COMMANDBATCH_XP","amount": 100}]}

Command Batching

Prerequisites

Overview

Initialization

Functionality

Player turns

Gave over

Setup

Requirements

Package

Role

Unity Cloud services configuration

Using the Deployment package

Using the Unity Dashboard

Cloud Code

Script

Parameters

Description

Location in project

Economy

Resource type

Resource name

ID

Description

Remote Config

Key

Type

Description

Value