Get started with CloudBehaviours

Deploy your first CloudBehaviour, then confirm your game can call it and receive updates.

Read time 5 minutes

Last updated 14 days ago

Important

This page describes an experimental feature that might change significantly before release. It's not recommended to use or rely on experimental features in production environments due to potential instability.

Create your first CloudBehaviour, connect your game to it, and call it.

Prerequisites

Before you start, confirm that your project meets the following prerequisites:

Unity 6.6 or later.
Cloud Code is set up in the Unity Editor. Follow the steps in Set up the Unity Editor to link your project to Unity Gaming Services, install the required packages and .NET, and set up the Deployment window. When you install the Cloud Code package, install the experimental version that includes CloudBehaviours: in Add package by name, enter
```
com.unity.services.cloudcode@3.1.0-exp.1
```
.

Note

MultiplayerSession

-scoped CloudBehaviour also requires the Multiplayer Services package (

com.unity.services.multiplayer

). The

Player

-scoped example on this page doesn't need it.

To confirm your installed package version carries CloudBehaviours, check that the Create > Services > Cloud Behaviour Script menu item exists. If it doesn't, your installed version doesn't include CloudBehaviours.

Create a CloudBehaviour script

To create a CloudBehaviour script:

In the Project window, select or create a folder to contain your CloudBehaviour.
Right-click the folder, then select Create > Services > Cloud Behaviour Script.
In the Cloud Behaviour Module Creator window, enter a name for the module and the script, then confirm.

The Editor creates a module folder with two assemblies: a

<Module>

assembly in the

Cloud

folder for your cloud script, and a

<Module>Client

assembly in the

Client

folder for your client bindings script. The Editor also creates a

<Module>.ccmu

file, and the module appears in the Deployment window as a Cloud Code module.

Write your cloud logic

The generated cloud script contains a class that inherits from

CloudBehaviour

. Scope is set to

Player

by default (

MultiplayerSession

scope requires an additional package). Edit the script in your configured external script editor, the same as any other Unity script. The following example is a simplified version of the generated script:


using Microsoft.Extensions.Logging;using Unity.Services.CloudBehaviours;using Unity.Services.CloudCode.Core;[StateScope(Scope.Player)]public class MatchState : CloudBehaviour{    public int Round;    public string SayHello(string name)    {        Round++;        Logger.LogDebug("Round {Round}", Round);        return $"Hello, {name}!";    }}

Each member you declare

public

maps to a CloudBehaviour feature:

```
Round
```
is a public field, so it becomes synchronized state that updates on the player's client. On a
```
MultiplayerSession
```
-scoped CloudBehaviour, synchronized state updates on every client in the session.
```
SayHello
```
is a public method, so it becomes an RPC that clients can call.

Private members stay in the cloud. The client bindings regenerate automatically when the script compiles.

Set up the client

The generated client script is a partial

MonoBehaviour

marked with the

CloudBehaviour

attribute:


using Unity.Services.CloudBehaviours;using UnityEngine;[CloudBehaviour(typeof(MatchState))]public partial class MatchStateClient : MonoBehaviour{    protected virtual void OnEnable() => EnableClient();    protected virtual void OnDisable() => DisableClient();}

Unity generates the rest of the partial class:

A method for each RPC.
A read-only property for each synchronized member: each synchronized field, and each per-player state view declared with
```
[SyncView]
```
.
A
```
UnityEvent
```
for each push channel that the cloud class declares.

The client lifecycle events

ScopeChanged

Synchronized

MessageReceived

Fatal

, and

Error

Important

If your cloud class has a

CCSG

error, Unity doesn't compile your client assembly, so none of these members exist until you fix it. The Console window shows the

CCSG

error on your cloud class. Fix it first.

To set up the client:

Attach the client bindings component to a GameObject in your scene.
Sign the player in. For a
```
MultiplayerSession
```
-scoped CloudBehaviour, also join a multiplayer session.

When

EnableClient()

runs, the binding resolves its scope and connects automatically:

Player
scope: The binding follows whichever player is signed in. To lock it to one specific player instead, set Target Player ID in the Inspector window, or call
```
EnableClient(playerId)
```
instead of
```
EnableClient()
```
in
```
OnEnable
```
. The binding then connects only while that player is signed in, so a later account switch doesn't redirect calls to another player's state.
MultiplayerSession
scope: The binding follows the single active session, once the player is signed in and has joined it. If your project runs more than one session at a time, choose which one to follow: set Target Session Type in the Inspector window, or call
```
EnableClient(sessionType)
```
instead of
```
EnableClient()
```
. Otherwise, the binding raises
```
Fatal
```
.

Get the player ID

For a

Player

-scoped CloudBehaviour, the client binding follows the signed-in player by default. To identify a specific player from a script, use

AuthenticationService.Instance.PlayerId

after sign-in completes.

Call the CloudBehaviour

After the client's scope resolves, your CloudBehaviour is hydrated with the latest state from the server and is ready to be used. Call RPCs and read synchronized state directly on the client bindings component:


[CloudBehaviour(typeof(MatchState))]public partial class MatchStateClient : MonoBehaviour{    protected virtual void OnEnable()    {        EnableClient();        Synchronized.AddListener(() => Debug.Log($"Round is now {Round}"));    }    protected virtual void OnDisable() => DisableClient();    public async void OnButtonClicked()    {        var greeting = await SayHello("World");        Debug.Log(greeting);    }}

Drive RPC calls from user input or from the

ScopeChanged

event, rather than immediately after

EnableClient()

ScopeChanged

raises whenever the scope changes, including when it's withdrawn, for example when the player signs out. Check that

Scope

isn't

null

before you call an RPC.

Run your CloudBehaviour

To iterate quickly, deploy your module to a local Cloud Code server and enter Play mode. The local server supports breakpoints, so you can debug your cloud logic like any other script.

When you're ready to test against live Unity Gaming Services, stop the local server, then deploy the module from the Deployment window. While the local Cloud Code server is running, the Deployment window deploys your modules to it instead of to Unity Gaming Services.

After deployment, enter Play mode. When the client's scope resolves, the binding's Inspector window shows the connection status and the current values of the synchronized state.

Next, explore Game organization in CloudBehaviours and the Turn-based game workflow to build out your game logic.

Documentation

Development

User Acquisition

Monetization

Industry

Cloud Code