Get started with CloudBehaviours

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

Read time 10 minutes

Last updated 2 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 a CloudBehaviour that keeps a counter for each player, connect your game to it, and call it from a script. When you finish, your game signs a player in, calls the CloudBehaviour, and receives the updated counter from the cloud.

This walkthrough uses a

Player

-scoped CloudBehaviour, which holds state for one signed-in player. For a CloudBehaviour that every player in a multiplayer session shares, refer to Turn-based game workflow. For an explanation of the component that connects your game to a CloudBehaviour, refer to Client bindings in CloudBehaviours.

Prerequisites

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

Your project uses Unity 6.7 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 (UGS), install the required packages and .NET, and set up the Deployment window.
The experimental version of the Cloud Code package (
```
com.unity.services.cloudcode
```
) that includes CloudBehaviours is installed. Follow the steps in Install a UPM package by name, with
```
com.unity.services.cloudcode
```
as the name and
```
3.1.0-exp.1
```
as the version. Enter the version explicitly, because Package Manager otherwise installs the latest released version, which doesn't include CloudBehaviours.
The ASP.NET Core Runtime 10.0 (Microsoft) is installed, so you can run your CloudBehaviour on a local Cloud Code server. The .NET Runtime download alone isn't enough to start the local server.
Important
In version 3.1.0-exp.1, if the .NET 9 runtime is installed alongside .NET 10, the local server runs on .NET 9 and can't load your module. To avoid this issue, uninstall the .NET 9 runtime, or launch the Editor with the
DOTNET_ROLL_FORWARD
environment variable set to
LatestMajor
.
If you use a
```
MultiplayerSession
```
-scoped CloudBehaviour, the Multiplayer Services package (
```
com.unity.services.multiplayer
```
) is installed. The
```
Player
```
-scoped example on this page doesn't need the Multiplayer Services package.

Note

Several Unity packages have display names that start with Multiplayer. CloudBehaviours require only the package with the ID

com.unity.services.multiplayer

. Check the package ID before you install a package.

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

Learn the CloudBehaviour workflow

A CloudBehaviour has two parts. The cloud script is a C# class that derives from

CloudBehaviour

and runs in Cloud Code, either on a local Cloud Code server or on the Cloud Code service. The client bindings are a component that the Editor generates from the cloud script. Your game uses the client bindings to call the cloud script and receive its state.

Building a CloudBehaviour involves the following stages:

Write the cloud script. Each public member of the class becomes a feature of the client bindings.
Add the generated client bindings component to a GameObject in the scene.
Sign the player in, so the client bindings component can connect to the player's CloudBehaviour.
Call RPCs, read synchronized state, and listen for push channel events from the game.
Run the CloudBehaviour on a local Cloud Code server, then deploy it to the Cloud Code service.

The workflow uses the following parts of the Unity Editor:

The Create > Services > Cloud Behaviour Script menu item, which creates the cloud script and the client bindings script.
The client bindings component in the Inspector window, which shows the connection status and the synchronized state.
The Cloud Code toolbar button, which starts and stops the local Cloud Code server.
The Deployment window, which deploys the module to the Cloud Code service.

This walkthrough uses RPCs, synchronized state, and a push channel. CloudBehaviours also support timers, per-player state views, access control, and calls between CloudBehaviours.

Create a CloudBehaviour

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.
Name the script
```
MyCloudBehaviour
```
.
In the Cloud Behaviour Module Creator window, enter
```
MyModule
```
as the module name, then select Confirm.

The Editor creates a

MyModule

folder that contains the following items:

A
```
Cloud
```
folder with the
```
MyModule
```
assembly, which holds your cloud script,
```
MyCloudBehaviour.cs
```
.
A
```
Client
```
folder with the
```
MyModuleClient
```
assembly, which holds your client bindings script,
```
MyCloudBehaviourClient.cs
```
.
A
```
MyModule.ccmu
```
file. The module appears in the Deployment window as a Cloud Code module.

The generated cloud script contains the following class. The generated file also contains a namespace and explanatory comments, which this example omits.


using System;using Microsoft.Extensions.Logging;using Unity.Services.CloudBehaviours;using Unity.Services.CloudCode.Core;[StateScope(Scope.Player)]public class MyCloudBehaviour : CloudBehaviour{    public int Counter = 0;    public event Action<string> OnSayHello;    public string SayHello(string name)    {        Counter++;        Logger.LogDebug($"Counter: {Counter}");        OnSayHello?.Invoke(name);        return $"Hello, {name}!";    }}

The following table describes how each public member of the class is exposed.

Member	Member type	Feature	Description
`Counter`	Public field	Synchronized state	Cloud Code stores the value for each player, and your game receives the current value.
`OnSayHello`	Public event	Push channel	Cloud Code notifies your game when `SayHello` runs.
`SayHello`	Public method	Remote procedure call (RPC)	Your game can call the method remotely.

You don't need to change the generated cloud script for this walkthrough. The Editor regenerates the client bindings automatically each time the cloud script compiles.

Add the client bindings to your scene

The client bindings script is a component that connects your game to the CloudBehaviour.

To add the client bindings component to your scene:

In the Hierarchy window, right-click and select Create Empty.
Rename the new GameObject to
```
CloudBehaviour
```
.
In the Inspector window, select Add Component, then search for and select My Cloud Behaviour Client.

The

CloudBehaviour

GameObject now has the My Cloud Behaviour Client component. The component connects to your CloudBehaviour after a player signs in, which you set up in the next section.

If My Cloud Behaviour Client isn't in the list, check the Console window for a

CCSG

error on your cloud script. The Editor doesn't generate client bindings until you fix the error. In version 3.1.0-exp.1, a project that includes the Netcode for Entities package reports

CCSG902

and

CCSG908

errors instead, and the Editor doesn't generate client bindings until you remove that package.

Sign the player in

Player

-scoped CloudBehaviour needs a signed-in player. The client bindings component connects automatically after the player signs in.

To sign the player in when your game starts:

In the Project window, right-click a folder outside the
```
MyModule
```
folder, such as
```
Assets
```
, then select Create > MonoBehaviour Script. The client assembly doesn't reference the Authentication package, so a script inside the
```
Client
```
folder can't sign the player in.
Name the script
```
SignIn
```
.
Double-click
```
SignIn.cs
```
to open it in your configured external script editor.

Replace the contents of the script with the following code, which initializes Unity Gaming Services and signs the player in anonymously:


using Unity.Services.Authentication;using Unity.Services.Core;using UnityEngine;public class SignIn : MonoBehaviour{    async void Start()    {        await UnityServices.InitializeAsync();        if (!AuthenticationService.Instance.IsSignedIn)            await AuthenticationService.Instance.SignInAnonymouslyAsync();        Debug.Log($"Signed in as player {AuthenticationService.Instance.PlayerId}.");    }}

In the Hierarchy window, select the
```
CloudBehaviour
```
GameObject.
In the Inspector window, select Add Component, then search for and select Sign In.

When your game starts, the Sign In component signs the player in, and the client bindings component connects to the player's CloudBehaviour.

Call the CloudBehaviour

After the player signs in, the client bindings component connects to the player's CloudBehaviour and raises the

ScopeChanged

event. Call RPCs from a

ScopeChanged

handler or from player input, rather than immediately after

EnableClient()

, because the client bindings component isn't connected yet at that point.

To call the CloudBehaviour when the client bindings component connects:

In the Project window, open the
```
MyModule/Client
```
folder, then double-click
```
MyCloudBehaviourClient.cs
```
to open it in your external script editor.

Replace the

MyCloudBehaviourClient

class with the following class. Keep the

using

directives and the namespace that the Editor generated. The class calls

SayHello

when the client bindings component connects, reads the updated

Counter

value, and logs each

OnSayHello

push channel event:


[CloudBehaviour(typeof(MyCloudBehaviour))]public partial class MyCloudBehaviourClient : MonoBehaviour{    protected virtual void OnEnable()    {        ScopeChanged.AddListener(OnScopeChanged);        OnSayHello.AddListener(OnHelloReceived);        EnableClient();    }    protected virtual void OnDisable()    {        DisableClient();        ScopeChanged.RemoveListener(OnScopeChanged);        OnSayHello.RemoveListener(OnHelloReceived);    }    async void OnScopeChanged()    {        // The scope is null when the player signs out.        if (Scope == null)            return;        var greeting = await SayHello("World");        Debug.Log($"{greeting} Counter is now {Counter}.");    }    void OnHelloReceived(string name)    {        Debug.Log($"Received the OnSayHello event for {name}.");    }}

Your client bindings script now calls

SayHello

each time the client bindings component connects. To test the script, run your CloudBehaviour on the local server.

Run your CloudBehaviour on the local server

Run your CloudBehaviour on a local Cloud Code server to iterate quickly. The local server supports breakpoints, so you can debug your cloud logic like any other script.

To run your CloudBehaviour on the local server:

Enable the Cloud Code toolbar button. Follow the steps in Enable the Cloud Code toolbar button.
Select the Cloud Code toolbar button, then select Start Local Server. The local server compiles and deploys every Cloud Code module in your project, including
```
MyModule
```
.
Enter Play mode.

After you enter Play mode, the Console window shows the following messages:

```
Signed in as player <player ID>.
```
```
Hello, World! Counter is now 1.
```

Received the OnSayHello event for World.

The push channel event and the RPC response arrive separately, so the

OnSayHello

message might appear before the

Hello, World!

message.

In the Inspector window, the client bindings component shows its connection status and the current value of

Counter

. Each time you enter Play mode,

Counter

increases by one, because Cloud Code stores

Player

-scoped state between sessions. To reset

Counter

, follow the steps in Reset local state.

If the Console window shows a

HydrationFailedOnConnect

error with the message

Module could not be found

, the local server wasn't running when you entered Play mode. Exit Play mode, start the local server, then enter Play mode again.

Run your CloudBehaviour on the Cloud Code service

While the local Cloud Code server runs, the Deployment window deploys your modules to the local server instead of to the Cloud Code service.

To run your CloudBehaviour on the Cloud Code service:

If the Editor is in Play mode, exit Play mode. The Editor chooses between the local server and the Cloud Code service when you enter Play mode, so your game keeps calling the local server until you exit Play mode.
Select the Cloud Code toolbar button, then select Stop Local Server.
Select Services > Deployment to open the Deployment window.
In the Deployment window, select
```
MyModule.ccmu
```
, then select Deploy Selected. The Deployment window deploys the module to the environment that's selected in the window.
Enter Play mode.

Your game connects to the CloudBehaviour on the Cloud Code service, and the Console window shows the same messages as on the local server. The

Counter

value in the Cloud Code service is separate from the value on the local server, so it starts again at

Get the player ID

A player ID identifies a signed-in player. The following table lists how to get the player ID, depending on where your code runs.

Where your code runs	How to get the player ID
Game client, after sign-in completes	`AuthenticationService.Instance.PlayerId`
Cloud script, in an RPC that a player calls	`Context.PlayerId`
Cloud script, for every player in a multiplayer session	`Context.Session.PlayerIds`
Cloud script, in a call from a timer or another service	`Context.PlayerId` is `null` . Pass the player ID as an endpoint argument instead.

For a

Player

-scoped CloudBehaviour, the client bindings component follows the signed-in player by default. To follow one specific player, pass the player ID to

EnableClient

after sign-in completes:


await AuthenticationService.Instance.SignInAnonymouslyAsync();EnableClient(AuthenticationService.Instance.PlayerId);

Get started with CloudBehaviours

Prerequisites

Learn the CloudBehaviour workflow

Create a CloudBehaviour

Member

Member type

Feature

Description

Add the client bindings to your scene

Sign the player in

Call the CloudBehaviour

Run your CloudBehaviour on the local server

Run your CloudBehaviour on the Cloud Code service

Get the player ID

Where your code runs

How to get the player ID

Additional resources