---
title: Get started with CloudBehaviours
product: Cloud Code
version: 3.0.0
latest_version: 3.0.0
status: This page documents version 3.0.0. The latest version is 3.0.0.
canonical: https://docs.unity.com/en-us/cloud-code/3.0.0/cloudbehaviours/get-started
latest_url: https://docs.unity.com/en-us/cloud-code/3.0.0/cloudbehaviours/get-started.md
last_updated: 2026-11-02
generated_at: 2026-11-04T14:17:22.311Z
locale: en-us
---

# Get started with CloudBehaviours

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

> **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](./turn-based-game-workflow.md). For an explanation of the component that connects your game to a CloudBehaviour, refer to [Client bindings in CloudBehaviours](./client-bindings.md).

## 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](../modules/getting-started#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](https://docs.unity3d.com/Manual/upm-ui-quick.html), 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](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) (Microsoft) is installed, so you can run your CloudBehaviour on a [local Cloud Code server](../modules/how-to-guides/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:

1. Write the cloud script. Each public member of the class becomes a feature of the client bindings.
2. Add the generated client bindings component to a GameObject in the scene.
3. Sign the player in, so the client bindings component can connect to the player's CloudBehaviour.
4. Call RPCs, read synchronized state, and listen for push channel events from the game.
5. 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](./timers.md), [per-player state views](./per-player-state-views.md), [access control](./access-control.md), and [calls between CloudBehaviours](./calling-another-behaviour.md).

## Create a CloudBehaviour

To create a CloudBehaviour script:

1. In the **Project** window, select or create a folder to contain your CloudBehaviour.
2. Right-click the folder, then select **Create** > **Services** > **Cloud Behaviour Script**.
3. Name the script `MyCloudBehaviour`.
4. 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.

```csharp title="Cloud/MyCloudBehaviour.cs"
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](./synchronized-state.md) | Cloud Code stores the value for each player, and your game receives the current value. |
| `OnSayHello` | Public event  | [Push channel](./push-channels.md)            | Cloud Code notifies your game when `SayHello` runs.                                    |
| `SayHello`   | Public method | [Remote procedure call (RPC)](./rpcs.md)      | 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:

1. In the **Hierarchy** window, right-click and select **Create Empty**.
2. Rename the new GameObject to `CloudBehaviour`.
3. 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

A `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:

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

2. Name the script `SignIn`.

3. Double-click `SignIn.cs` to open it in your [configured external script editor](../modules/how-to-guides/write-modules/unity-editor).

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

   ```csharp title="SignIn.cs"
   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}.");
       }
   }
   ```

5. In the **Hierarchy** window, select the `CloudBehaviour` GameObject.

6. 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:

1. In the **Project** window, open the `MyModule/Client` folder, then double-click `MyCloudBehaviourClient.cs` to open it in your external script editor.
2. 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:

   ```csharp title="Client/MyCloudBehaviourClient.cs"
   [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 the local server

Run your CloudBehaviour on a [local Cloud Code server](../modules/how-to-guides/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:

1. Enable the **Cloud Code** toolbar button. Follow the steps in [Enable the Cloud Code toolbar button](../modules/how-to-guides/local-cloud-code-server#enable-the-cloud-code-toolbar-button).
2. 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`.
3. 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](../modules/how-to-guides/local-cloud-code-server#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:

1. 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.
2. Select the **Cloud Code** toolbar button, then select **Stop Local Server**.
3. Select **Services** > **Deployment** to open the **Deployment** window.
4. 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.
5. 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 `1`.

## 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:

```csharp title="Following one specific player"
await AuthenticationService.Instance.SignInAnonymouslyAsync();
EnableClient(AuthenticationService.Instance.PlayerId);
```

## Additional resources

* [Client bindings in CloudBehaviours](./client-bindings.md)
* [Turn-based game workflow](./turn-based-game-workflow.md)
* [Game organization in CloudBehaviours](./organize-your-game-into-behaviours.md)
* [RPCs in CloudBehaviours](./rpcs.md)
* [Synchronized state in CloudBehaviours](./synchronized-state.md)
* [Local Cloud Code server](../modules/how-to-guides/local-cloud-code-server)