Client bindings in CloudBehaviours

Understand the generated component that connects your game to a CloudBehaviour, and how it resolves its scope and reports its state.

Read time 4 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.

The client bindings are a generated

MonoBehaviour

component that connects your game to a CloudBehaviour. The component exposes the CloudBehaviour's RPCs, synchronized state, and push channels as members you can use from your game. It also resolves which scope instance to connect to, and raises lifecycle events that report its connection state.

For a walkthrough that sets up client bindings in a scene, refer to Get started with CloudBehaviours.

Client bindings script

When you create a CloudBehaviour, the Editor creates a client bindings script in the module's

Client

folder. The script is a partial

MonoBehaviour

class marked with the

[CloudBehaviour]

attribute:


[CloudBehaviour(typeof(MyCloudBehaviour))]public partial class MyCloudBehaviourClient : MonoBehaviour{    protected virtual void OnEnable() => EnableClient();    protected virtual void OnDisable() => DisableClient();}

The Editor generates the rest of the partial class each time the cloud script compiles. The generated part contains the following members:

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

The

ScopeChanged

Synchronized

MessageReceived

Fatal

, and

Error

lifecycle events.

The
```
Scope
```
property, which holds the scope that the component is connected to, or
```
null
```
when the component isn't connected.
The
```
Hydrate
```
method, which fetches the current server state and applies it to the synchronized properties.

Important

If your cloud script has a

CCSG

error, the Editor doesn't generate your client bindings, so it never compiles the client assembly. None of these members exist until you fix the error. The Console window shows the

CCSG

error on your cloud script. Fix the error first.

Scope resolution

When

EnableClient()

runs, the client bindings component resolves its scope and connects automatically. How the component resolves its scope depends on the CloudBehaviour's

[StateScope]

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

Before the scope resolves, the client bindings component isn't connected, and an RPC call can't reach the CloudBehaviour. Trigger RPC calls from player input or from the

ScopeChanged

event, rather than immediately after

EnableClient()

Lifecycle events

The client bindings component raises lifecycle events to report changes to its connection and state. The following table describes each lifecycle event.

Event	Description
`ScopeChanged`	Raised when the scope changes or is withdrawn, such as when the player signs out. When a scope resolves, the synchronized properties are already up to date. Check that `Scope` isn't `null` before you call an RPC.
`Synchronized`	Raised after the component applies the server state to the synchronized properties. This event doesn't indicate which properties changed.
`MessageReceived`	Raised whenever the component receives a message. The synchronized properties are already up to date when this event is raised.
`Fatal`	Raised when the component encounters a failure from which it can't recover. The component is already disabled when this event is raised. To reconnect, call `EnableClient()` again, but don't call it from the `Fatal` handler.
`Error`	Raised when a failure occurs that doesn't stop the component. The component keeps its scope. To find out what failed and whether to retry, read the `Reason` property of the `CloudBehaviourError` argument.

State updates

The client bindings component applies server state to its synchronized properties in the following situations:

An RPC call returns.
A push message arrives, either a synchronized state update or a push channel event.
The scope resolves.
A
```
Hydrate
```
call completes.

Push messages reach only connected clients. To catch up on state that changed while the component wasn't connected, call

Hydrate

The Inspector window of the client bindings component shows the connection status and the current values of the synchronized state.

Cloud Code

Cloud Code

Client bindings in CloudBehaviours

Client bindings script

Scope resolution

Lifecycle events

Event

Description

State updates

Additional resources