Idle clicker game#

In real-time idle clicker and social games, such as farming or city-building games, common considerations include:

• How to simulate real-time activities in a game that is not running all the time.
• How the simulation can occur on the cloud, to ensure that all players' games are updated properly, regardless of timezone or any modifications to the date and time on a player's device.

This sample use case shows how to solve both challenges while limiting calls to Unity Gaming Services, which can cause throttling issues or increased costs.

In this sample, the player uses a resource (Water) to purchase Wells, which each produce 1 unit of Water per second.

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 Idle Clicker Game. To open this scene directly and interact with the use case:

1. In the Unity Editor Project window, select Assets > Use Case Samples > Idle Clicker Game, then double-click IdleClickerSample.unity to open the sample scene.
2. Press Play to enter Play mode.

The IdleClickerSceneManager.cs script performs the following initialization tasks in its Start function:

1. Initializes Unity Gaming Services.

2. 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.

3. Retrieves and updates the player's currency balances from the Economy service.

4. Retrieves or creates the current game state.

   Note: If the game is already in progress, this step grants Water based on the quantity produced by all Wells since the last time the game state was updated.

5. Enables button-click functionality for the available tiles in the play field.

Functionality#

Placing Wells#

You can click any open tile in the play field to place a Well in exchange for 500 Water. Cloud Code validates whether you’re attempting to place a Well in an empty tile. When you click a tile, the following occurs:

1. Cloud Code calculates the amount of Water generated since the last update, then calls the Economy service to grant that amount to the player’s currency balance (see section on real-time resource updates, below).
2. The IdleClicker_PlaceWell.js Cloud Code script checks that the requested tileisn't occupied.
3. If the tile is available, the script attempts a Virtual Purchase through the Economy service that will deduct 500 Coins and return success or failure based on the transaction outcome.
4. If the Virtual Purchase succeeds, Cloud Code updates the game state with newly the added piece and returns a new state to the client.

If the Virtual Purchase fails, Cloud Code throws an exception back to the client that then displays a pop-up message explaining what happened.

Real-time resource updates#

Between moves, while the player is viewing the game scene but not interacting, the client simulates Water production and updates the Currency HUD accordingly. Each Well produces one Water per second. Because this sample game is intended to be real-time, whenever the client calls Cloud Code, it checks the current time and calculates how much cumulative Water has been produced by each Well since its last production cycle. Every time the game loads, or the player attempts to place a Well, the following occurs:

1. To determine how much time has passed, Cloud Save stores timestamps for the last time each Well produced Water, along with the full game state that includes obstacle locations, Well locations, and the last update time.
2. After the Economy service grants the appropriate quantity of Water, each Well’s timestamp is updated, and the fully-updated state is saved back to Cloud Save.

Note: Because the Water quantity displayed in the currency HUD is simulated by the client and not actually in sync with the server until the scene is reloaded or the player attempts to place a Well, its server-side values will often appear inaccurate.

Virtual purchases#

This sample illustrates how virtual purchases occur through the Economy service. In this case, the virtual purchase for a Well costs 500 Water, but, unlike most virtual purchases, the purchase itself does not actually grant anything. Instead, the virtual purchase consumes the transaction cost (500 Water) and updates the game state with a new Well in the corresponding tile. Cloud Save stores the full game state, including the locations of Wells and obstacles.

Note: The service only attempts the transaction after confirming that the space is empty.

Setup#

Requirements#

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

To use these services in your game, activate each service for your Organization and project in the Unity Cloud 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

To configure these items you can use the Deployment package, or manually enter them using the Unity Cloud 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:

1. Open the Deployment window.
2. Check in Common and Idle Clicker Game.
3. Click Deploy Selection.

This deploys all the necessary items.

Using the Unity Cloud Dashboard#

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

Cloud Code#

Publish the following scripts in the Unity Cloud Dashboard:

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 resource in the Unity Cloud Dashboard:

In addition, configure the following virtual purchase for the battle pass:

* The Well itself is not granted by the virtual purchase; Cloud Code adds it to the game state directly upon a successful transaction.